Try free

Last updated 13 October 2026

Claude Code missing environment variables

Identifying the missing variable error

You start a session with the command claude and ask the agent to run a deployment script or a database migration. The agent uses the Bash tool to execute your command, but the process fails immediately. The error message says an environment variable is missing or undefined. You know the variable exists in your local shell because you can echo it right now, yet the agent acts as if the environment is empty. This disconnect happens because the agent does not always automatically source your shell configuration files when it spawns a new sub-process.

This issue surfaces when you rely on variables defined in your shell profile like .zshrc or .bash-profile. While your interactive terminal session has these variables in memory, the environment passed to the Bash tool inside the agent session might be stripped or isolated. The agent works in a clean room where it only knows what was explicitly handed to it or what it can discover through the tools at its disposal. You might see this when trying to use cloud provider credentials, local development keys, or custom paths that are not in the standard system path.

Inheriting the environment from the parent process

The most direct way to ensure the agent sees your variables is to export them in your terminal before you run the claude command. If you type export API-KEY=value and then start the session, the agent process inherits that specific environment. Any time the agent uses the Bash tool to run a command, that sub-process also receives those inherited variables. This is the simplest fix for one-off sessions where you need a specific secret or configuration value available for a short duration.

However, this method requires you to remember to set the variables every time you open a new terminal tab. If you close the terminal or start a new session elsewhere, those variables disappear. Many developers find this manual step tedious, especially when juggling multiple microservices or projects. You must verify that your variables are truly exported and not just local shell variables, as local variables do not pass down to child processes like the agent. Use the export command specifically to ensure the variable moves from your shell into the agent session.

Providing project instructions in CLAUDE.md

You can use the CLAUDE.md file in your project root to provide explicit instructions about the environment. If your project requires specific variables to run tests or build assets, document them in this file. The agent reads CLAUDE.md at the start of the session to understand project norms and requirements. You can instruct the agent to check for the presence of certain variables before it attempts to run any scripts. This prevents the agent from guessing why a command failed and allows it to ask you for the missing information.

Within CLAUDE.md, you should specify the names of the required variables and where they usually come from. For example, tell the agent that it should look for a .env file or that it should expect certain keys to be available in the shell environment. When the agent knows what to look for, it can use the Read tool to inspect local configuration files. It can then use those values to construct the correct commands or even suggest that you set them if they are missing. This turns a silent failure into a managed project requirement that the agent understands and can help resolve.

Managing multiple environments with adhdTerminal

When you work on several projects at once, environment variable management becomes a significant burden. You might have different keys for a staging environment in one project and a production environment in another. Running multiple sessions of Claude Code in the same terminal can lead to cross-contamination of variables or simple confusion. This is where adhdTerminal provides a structural solution. The app runs many Claude Code sessions side by side on a single wall, where each tile represents a specific project or task with its own separate environment.

Each tile in adhdTerminal maintains its own context and session state. Because tiles reopen in the same place and resume the same session after a restart, you do not have to reconfigure your environment every morning. You can set up a tile for a specific backend service with its required variables and another tile for a frontend project. The visual feedback on the wall shows you which sessions are active or waiting for your input. This separation ensures that you never accidentally run a script in one project using the environment variables intended for another.

Configuring shell hooks for environment loading

The agent supports hook events that trigger at specific points in a session. You can use the SessionStart hook to run logic that prepares your environment. While the agent does not have a native command to load an environment file, you can use these hooks to ensure the environment is ready. For instance, you could write a script that checks for a .env file and exports its contents, then trigger that script when the session begins. This automation removes the need for manual exports and keeps your environment consistent across different sessions.

You define these hooks in your settings.json or through custom commands in the .claude/commands directory. By leveraging the UserPromptSubmit or SessionStart hooks, you can create a workflow where the agent always has the latest configuration. This is particularly useful if your project uses a tool like direnv or shadow-env to manage local variables. You can tell the agent to respect these tools or simulate their behavior so that the Bash tool always operates with the correct context. This approach makes your development environment more resilient and less prone to manual errors.

Debugging environment issues with built-in tools

If your variables still seem to be missing, use the claude doctor command to check the health of your installation. This command performs a series of checks to ensure the agent can interact with your system correctly. While it may not list every environment variable, it can identify issues with your shell integration or permissions. If the doctor command reports everything is fine, the issue is likely with how the variables are scoped or exported in your specific shell configuration. If you use adhdTerminal, you can easily compare the environment of different tiles to see where a configuration might be failing.

You can also use the Bash tool directly to debug the environment from within an active session. Ask the agent to run a command like env or printenv to see exactly what variables are visible to it. If you see a variable in your terminal but not in the output of the agent's Bash tool, you know the inheritance is breaking at the process boundary. You can then use the /terminal-setup command to review how the agent interacts with your terminal. This helps you identify if a specific shell plugin or configuration is interfering with how environment variables are passed to sub-processes.

Handling secrets and sensitive variables

Security is a primary concern when dealing with environment variables, especially those containing API keys or passwords. You should never hardcode these secrets into CLAUDE.md or any file that is tracked by your version control system. Claude Code respects your .gitignore file, so ensure your .env files are properly ignored. When the agent needs to use a secret, it is better to have it available in the shell environment or a local untracked file like .claude/settings.local.json.

You can use the /permissions command to control how the agent interacts with your sensitive data. If you are concerned about the agent reading certain files or using specific tools with your variables, you can set restrictions in your settings.json file. The agent can operate in different modes like plan or acceptEdits to give you more control over what it does with your environment. This layered approach to security allows you to take advantage of the agent's power while maintaining strict control over your most sensitive configuration data.

Automating environment checks with custom commands

To make your workflow even more efficient, you can create custom slash commands in the .claude/commands directory. Create a markdown file that defines a command to verify your development environment. This command can check for required variables, verify connection strings, and ensure all necessary services are running. When you start a new session, you can run this custom command to get a quick report on your environment's readiness. This saves you from manually verifying the shell state every time you return to a project.

This automation is especially helpful when onboarding new team members or switching between different machines. By standardizing your environment checks as custom commands, you ensure that the agent always has the information it needs to succeed. You can also share these commands across your team to create a consistent development experience. This turns the problem of missing environment variables into a solved part of your project's infrastructure, allowing you to focus on writing code rather than debugging your shell configuration. Standardized checks ensure that the agent can work independently without constant manual intervention.

Questions people ask

How do I make the agent see a variable I just added to my .zshrc file?

You must restart your terminal or source the file manually before running the claude command. The agent inherits the environment from the shell where it was launched. If you update your configuration while a session is active, the agent will not see those changes until you start a new session.

Can I use the /config command to set environment variables?

The /config command is for agent settings and does not directly set shell environment variables. To make variables available to the agent, you should export them in your terminal or define them in local project files. You can also use hook events to automate the loading of variables at the start of a session.

Does the agent have access to the variables set in my IDE?

If you run the agent inside an integrated terminal within your IDE, it will usually inherit the variables that the IDE provides to that terminal. However, if you are using a standalone terminal, it will only see the variables defined in that specific shell environment. Use the /terminal-setup command to ensure the agent is correctly integrated with your preferred environment.

Read next

More on when it goes wrong·All posts