Find suggested solutions for common errors while working with environment variables.

Your client-side code can’t access a variable that you prefixed with PUBLIC__.

Cause: A single underscore or missing prefix means the variable is treated as server-only.

Suggested Solution: Verify the variable name starts with PUBLIC__ (two underscores).

Your app fails to start and displays a config path error.

Cause: The path in your PUBLIC__ variable name isn’t found in config.server.ts.

Suggested Solution: The path in your PUBLIC__ variable name must exist in config.server.ts. Add the field and its default value to the config before setting the environment variable.

Your code throws an Error stating that a variable is missing.

Cause: The environment variable that the code calls isn’t set.

Suggested Solution: Call the projects_target_env_var_partial_update API endpoint to set the applicable environment variable.

Your code logs an error message stating that the environment variable wasn’t found.

Cause: The code couldn’t find the environment variable because of a typo or incorrect variable name.

Suggested Solution: Confirm that you spelled the environment variable name correctly and that you’re using the right name. To see all set variables, call the projects_target_env_var_list API endpoint.

Your API call to set an environment variable fails.

Cause: The environment variable name doesn’t comply with the constraints. For example, the variable value exceeds 32 KB.

Suggested Solution: Confirm that your environment variable complies with the constraints.

Authentication errors occur when you execute code that uses an API key.

Cause: The API key that you used when you set the environment variable isn’t in the expected format or is missing.

Suggested Solution: Confirm that the API key stored by an environment variable is correct. If needed, call the projects_target_env_var_partial_update API endpoint to correct the API key.

A fetch request fails with a network error.

Cause: A URL for an API endpoint in your code is missing or invalid. For example, the URL for a content management system (CMS) endpoint is incorrect.

Suggested Solution: Confirm that any URLs for API endpoints in your code are correct.

Cause: Environment variables load at startup. A running server doesn’t pick up changes automatically.

Suggested Solution: Restart your dev server.

Cause: A single underscore or missing prefix marks the variable as server-only.

Suggested Solution: Verify that the variable name starts with PUBLIC__ (two underscores).

Cause: The path in your PUBLIC__ variable name isn’t found in config.server.ts.

Suggested Solution: Add the path and its default value to config.server.ts before setting the environment variable.

Cause: The variable value isn’t formatted correctly for its type. The app parses values automatically.

Suggested Solution: For booleans, use the string true or false. For arrays and objects, use valid JSON. Confirm the value is formatted correctly in your .env file or in Runtime Admin.

Cause: This error can be caused by insufficient permissions, an invalid API key, or a reserved prefix.

Suggested Solution: Confirm that you have the developer or admin role on the project. Verify that your MRT API key is valid. Check that the variable name doesn’t use a reserved prefix.

Cause: You likely didn’t deploy the bundle after setting the variable.

Suggested Solution: Make sure that you deployed your bundle after setting the variable. Existing running instances use the variables that were active at deploy time.