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.
j
