Troubleshooting and FAQs
Relevant source files
The following files were used as context for generating this wiki page:
This page provides technical guidance on resolving common issues, understanding system warnings, and answering frequently asked questions regarding Docktree's orchestration of Docker Compose across git worktrees. It covers configuration conflicts, environment variable mismatches, and shared service isolation.
Docktree operates by generating dynamic overrides to prevent collisions in project names, host ports, and container names. When issues arise, they typically stem from environment configuration or platform-tier service definitions that interfere with this isolation logic.
Environment and Port Remapping
One of the primary sources of confusion in Docktree is the automatic remapping of ports. Docktree allocates unique host ports from a range (default 41000–49999) to prevent collisions between worktrees.
Common Environment Warnings
During docktree up, the system performs an "env check" to identify variables that might conflict with Docktree's internal project management.
| Variable/Pattern | Impact | Guidance |
|---|---|---|
COMPOSE_PROJECT_NAME | Low | Docktree overrides this with a unique project name; the .env value is ignored. |
COMPOSE_FILE | Low | Docktree uses this to select files, but internal logic ensures the worktree context wins. |
PORT or PUBLISHED | Medium | If your application hardcodes these values from .env, it may fail to connect after Docktree remaps them. |
Sources: internal/compose/envcheck.go:34-45, internal/cli/up.go:121-125
The diagram shows how Docktree evaluates a worktree's .env file for potential conflicts before starting services.
Sources: internal/compose/envcheck.go:21-48
Shared Services and Tenancy Issues
When using shared.services (the Platform Tier), Docktree manages the lifecycle of shared infrastructure like databases. Issues often occur when the application cannot "see" the rewritten connection strings.
Secrets Wrappers Visibility
If an application uses a secrets wrapper (e.g., Infisical, Doppler, Vault), the environment variables are often injected at runtime inside the container. Because Docktree operates at the Compose orchestration layer, it cannot "see" or rewrite these internal variables.
Solution: Ensure the application is configured to read DATABASE_URL (or equivalent) directly from the environment provided by Docktree, or set the service to tenancy: isolated to avoid the platform tier.
Sources: internal/cli/init.go:94-98, README.md:92-98
Tenancy Mode Mismatch
Docktree supports two primary tenancy modes for shared databases:
- full_share: All worktrees connect to the same instance and the same database.
- per_database: All worktrees connect to the same instance but get a unique, isolated database schema.
If tenancy: per_database is selected but url_envs (e.g., DATABASE_URL) is not declared in docktree.yml, Docktree will not rewrite the connection string, leading to a loss of isolation where all worktrees hit the same database.
Sources: internal/cli/up.go:145-155, internal/cli/init.go:193-200
Resource Cleanup
Stale resources (containers, networks, and ports) can accumulate if worktrees are deleted manually via git worktree remove without running docktree down.
Using docktree clean
The clean command identifies resources belonging to worktrees that no longer exist on disk.
- Dry Run: Always run
docktree clean --dry-runfirst to see what will be removed. - Volumes: By default,
cleandoes not remove volumes. Usedocktree clean --volumesto include them. - Non-interactive: In CI or automation, use
--yesto skip confirmation prompts.
Sources: internal/cli/help_doc.go:117-127, skills/docktree/SKILL.md:61-63
This diagram illustrates the logic used to identify and prune resources that are no longer associated with active git worktrees.
Sources: internal/cli/render.go:323-360, internal/cli/help_doc.go:117-127
Frequently Asked Questions (FAQ)
How do I see which ports are assigned to my worktrees?
Run docktree ports. To see a map of all ports across all active worktrees in the repository, use docktree ports --all. This is particularly useful for discovering the URLs of sibling worktrees without switching directories.
Sources: README.md:58, skills/docktree/SKILL.md:57-59
Why is docktree up failing with a "Port Bind" error?
Docktree attempts to allocate ports that are free in its own internal registry. However, if an external process (outside of Docktree) binds to a port in the 41000-49999 range, Docker will return a bind error. Docktree includes retry logic that will attempt to release and re-allocate a different port up to 10 times before failing.
Sources: internal/cli/up.go:253-272
Can I use my own Docker Compose flags?
Yes. Docktree supports "passthrough" for standard Compose commands like logs, exec, build, and ps. Docktree pre-fills the project context (project name and file paths) so you don't have to.
Sources: README.md:63-66, skills/docktree/SKILL.md:32-34
Does Docktree work on Windows?
Docktree is supported on Windows only through WSL2 with Docker Desktop WSL integration enabled. Native Windows (CMD/PowerShell) is not supported.
Sources: README.md:103-107, install.sh:41-43
How do I handle files like .env that are git-ignored but needed in every worktree?
Use the docktree sync command. When files are defined in the setup.copy section of docktree.yml, running sync will propagate the versions from the main repository root to all existing worktrees.
Sources: internal/cli/render.go:498-508, internal/cli/help_doc.go:207-217
Conclusion
Troubleshooting in Docktree primarily involves verifying that the application respects the dynamically allocated ports and ensuring that the shared.services configuration accurately reflects how the application consumes infrastructure. By utilizing the status, ports, and clean commands, developers can maintain a healthy, isolated development environment across numerous concurrent branches.