# Why a new agent worktree cannot build: env files and dependencies

> Diagnose missing .env files, local packages, Python environments, ports, and shared services before blaming the coding agent.

Canonical HTML: https://canopyide.dev/guides/fix-missing-env-and-dependencies-in-agent-worktree
Article date: 2026-09-28

A Git worktree gives an agent a separate checkout of tracked files. It does not clone every local setup choice from your first checkout. When the second agent fails before touching code, inspect the environment first.

## Separate source failures from setup failures

Record the exact command, checkout path, first error, and whether the main checkout runs the same command. If a package import fails before your changed code executes, ask whether dependencies were installed in the new directory. If a service says a key or URL is missing, check the project's documented environment setup. Avoid sending an agent on a code rewrite when the problem is a missing local input.

## Understand what Git copied

A worktree checks out repository content at a branch or commit. A file such as .env.local that is intentionally ignored is untracked and will not appear just because a new worktree exists. Likewise, node_modules, build output, and Python virtual environments are usually local to a directory. Do not assume a symlink or copied environment is safe: Python documents virtual environments as generally nonportable, and package setups can embed paths or platform-specific binaries.

## Recreate dependencies through the project command

From the new checkout, use the lockfile and install command the repository documents. For a Python project, create a new virtual environment and install from its declared dependency file or lockfile. For a JavaScript project, install with its chosen package manager rather than copying another checkout's node_modules. Confirm the runtime version and the run command before handing the tree to an agent.

## Provide configuration without leaking secrets

Prefer a checked-in .env.example containing names and harmless placeholders, plus a secure way to supply actual values. Decide whether this agent needs the real service or a local test substitute. Copy a real .env only when your project's policy allows it, keep it ignored, and never paste secrets into a prompt, PR, log, or screenshot. Canopy's current-main README says it prepares ignored configuration for worktrees, but check the installed release and inspect what was prepared before running a command that uses credentials.

## Identify services and ports by checkout

A healthy build can still preview the wrong branch when two dev servers compete for one port. Give each checkout its own frontend port, verify the process output in Canopy Servers, and open the reported URL. Write down which database, API, worker, or cache each tree uses. Two branches sharing one stateful service can contaminate tests even when their files are separate.

## Finish with a clean setup note

After the second checkout runs, add only safe, repeatable steps to the repository README or task brief: runtime version, install command, environment variable names, service dependencies, and run command. Keep actual values in the approved secret store. A reproducible setup helps the next agent more than a private fix hidden in one terminal history.

## Copyable resources

### Worktree environment triage

Run only the commands that match your project's tooling; never include secret values in the report.

````text
Checkout and branch: [path] / [branch]
Command and first error: [exact command; redact credentials]
Tracked files present? git status --short; git ls-files | head
Ignored config expected? git check-ignore -v .env.local
Runtime and install command from README/lockfile: [ ]
Local dependencies installed in this checkout? [yes/no]
Services needed and their actual URLs/ports: [ ]
Can the same command run in the main checkout? [yes/no]
Next action: recreate setup, change service configuration, or investigate source code.
````

## Frequently asked questions

### Why is my .env file missing in a new Git worktree?

If it is ignored and untracked, Git does not check it out. Use a safe project-specific method to provide required values; do not commit secrets to make worktrees easier.

### Can two worktrees share one node_modules directory or Python venv?

Some projects may support shared dependency caches, but do not assume copied installation directories or virtual environments are portable. Follow the project's install process in each checkout.

## Sources and further reading

- [Git worktree documentation](https://git-scm.com/docs/git-worktree)
- [Git ignore documentation](https://git-scm.com/docs/gitignore)
- [Python virtual environment documentation](https://docs.python.org/3/library/venv.html)
- [Canopy app README: worktree setup](https://github.com/FluidWorksApp/canopy-ide/blob/main/README.md)

## Related Canopy pages

- [Git worktrees for parallel coding agents: commands and cleanup](https://canopyide.dev/guides/git-worktrees-for-parallel-coding-agents.md)
- [How do I stop two agent worktrees from using the same port?](https://canopyide.dev/use-cases/avoid-dev-server-port-collisions-with-worktrees.md)
- [How do I start my website, API, and worker with one click?](https://canopyide.dev/use-cases/one-click-local-dev-stack.md)
- [Canopy Remote, Claude Code, Copilot CLI, or SSH from your phone?](https://canopyide.dev/use-cases/canopy-remote-vs-claude-code-copilot-ssh.md)
- [Canopy vs Replit Agent for building an app](https://canopyide.dev/use-cases/canopy-vs-replit-agent-for-building-apps.md)

Canopy runs installed coding CLIs; CLI accounts, model selection, and provider billing remain separate. Check the installed release before relying on version-specific behavior.