Atlas raises WorktreeNotGitError because the project directory you pointed a worktree operation at is not a git repository, and the fix is to run `git status` inside that directory to confirm, then initialize the repo before retrying. Atlas models each worktree failure mode as its own tagged error, so WorktreeCreateFailedError, WorktreeListFailedError, and WorktreeStartCommandFailedError each mean something different. Read the tagged error name in the response before you change anything.
Why does Atlas raise WorktreeNotGitError
Atlas raises WorktreeNotGitError for 1 reason: the directory the worktree operation targeted is not a git repository. The Atlas worktree service models not-a-git-repo as its own tagged error rather than folding it into a generic failure, so the tag names the problem precisely.
Git worktrees are a git feature, so a directory with no git repository in it has no worktrees to create, list, or remove. Atlas checks and reports that condition under its own tag instead of letting a confusing git error leak through. The Atlas worktree service enumerates 7 distinct failure modes: not-a-git-repo, name generation, create, start command, remove, reset, and list. WorktreeNotGitError is the first of them, and it fires before anything else has a chance to go wrong. Seeing it means the fix is about the repository, not about the worktree operation itself.
How to fix WorktreeNotGitError in Atlas
Fix WorktreeNotGitError in 2 steps. First, confirm the project directory is a git repository by running `git status` inside it. Second, if it is not a repository, initialize the repo first. Atlas can do the initialization, and it throws "Git is not installed" if git is absent.
Running `git status` inside the directory is the fastest possible check, and it distinguishes a genuinely uninitialized directory from a path mistake where you are one level above or below the actual repository root. If `git status` reports that you are not in a git repository, initialize it. If `git status` works fine, then the directory Atlas targeted is not the directory you think it is, and the path in your configuration is the thing to correct. Note the dependency chain: initialization needs git on PATH, and Atlas will say "Git is not installed" if it is missing.
What WorktreeStartCommandFailedError means in Atlas
WorktreeStartCommandFailedError means the Atlas worktree was created successfully but your configured start command failed afterward. It is 1 of the 7 failure modes the Atlas worktree service models as tagged errors, and unlike WorktreeNotGitError the repository and the worktree are both fine, so repair the start command.
The distinction saves real time. A developer who sees any worktree error and immediately starts re-initializing git will make no progress against WorktreeStartCommandFailedError, because git was never the problem. The Atlas worktree service separates start command from create precisely so you can tell the two apart. When the tag says start command, go look at the command you configured to run inside a new worktree, run it by hand in that worktree, and read its output. Fix the command, then retry, and the worktree creation itself will not need to be repeated.
How to tell an Atlas create failure from a list failure
Read the tagged error name in the Atlas API response. The Atlas worktree service models 7 failure modes as distinct tagged errors, including WorktreeCreateFailedError and WorktreeListFailedError, and maps all of them onto a single WorktreeError response, so the tag is the only thing that tells you which stage actually failed.
A create failure means Atlas could not produce the worktree at all. A list failure means Atlas could not enumerate the worktrees that exist. The remedies do not overlap, and treating one as the other wastes a debugging cycle. Because the Atlas worktree service also tags name generation, remove, and reset separately, the tag set is a diagnostic map: whichever tag comes back names the exact stage that broke. Start every worktree investigation by reading the tag, before you look at paths, commands, or git state. The tag is the fastest information in the response.
How to verify the Atlas worktree fix worked
Verify the fix by running `git status` in the project directory and then retrying the Atlas worktree operation. Success in 2026 means none of the tagged errors comes back: no WorktreeNotGitError, no WorktreeCreateFailedError, and no WorktreeListFailedError inside the WorktreeError response from the Atlas API.
Verify in the same directory that failed, because a worktree operation is scoped to a specific project path and a different path proves nothing. If `git status` now works but Atlas still returns a tagged worktree error, read the new tag: you have likely moved past not-a-git-repo and into a later stage such as create or start command. That progression is good news, not a regression. Each tag you clear is a stage that now works, and the Atlas worktree service will keep naming the next failing stage until the operation completes clean.
Do Atlas worktrees require git to be installed
Yes. Atlas worktrees require git, and initialization throws "Git is not installed" when git is absent from PATH. Atlas reads git branches, status, and diffs, and can stage and create commits on your behalf, so in 2026 a git binary remains a prerequisite for every worktree operation Atlas exposes.
The dependency shows up in a specific order when you are recovering from WorktreeNotGitError. You confirm the directory is a repository with `git status`. If it is not, you initialize it, and initialization itself needs git. If git is missing, Atlas says so with its own message rather than failing obscurely. Atlas snapshots file changes as git patches so edits can be diffed and rolled back, which is another reason git is not optional here. Install git first, then initialize, then retry the worktree operation, in that order.
How to fix it
- 01Confirm the project directory is a git repository; run `git status` inside it.
- 02Initialize the repo first. Atlas can do this, and it throws "Git is not installed" if git is absent.
- 03If the failure is WorktreeStartCommandFailedError, the worktree was created but your configured start command failed; fix that command.
- 04Read the tagged error name in the response to tell a create failure from a list failure.
Frequently asked questions
- What is WorktreeNotGitError in Atlas?
- WorktreeNotGitError is the Atlas tagged error for a worktree operation run against a directory that is not a git repository. The Atlas worktree service models not-a-git-repo as its own failure mode.
- How do I fix Atlas worktree operations failing outside a git repo?
- Confirm the project directory is a git repository by running `git status` inside it, then initialize the repo if it is not. Atlas can initialize it, and it throws "Git is not installed" if git is absent.
- What does WorktreeStartCommandFailedError mean?
- WorktreeStartCommandFailedError means the Atlas worktree was created but your configured start command failed. Fix that command; the git repository and the worktree itself are not the problem.
- How do I tell an Atlas worktree create failure from a list failure?
- Read the tagged error name in the response. WorktreeCreateFailedError and WorktreeListFailedError are separate tags, and the Atlas API maps every worktree failure onto a WorktreeError response.
- What failure modes does the Atlas worktree service track?
- The Atlas worktree service models each failure mode as its own tagged error: not-a-git-repo, name generation, create, start command, remove, reset, and list.
- Can Atlas initialize the git repository for me?
- Yes. Atlas can initialize the repo, which is the documented fix when a worktree operation fails with WorktreeNotGitError. If git is not on PATH, initialization throws "Git is not installed" instead.
- Why did my Atlas worktree error change after I initialized git?
- A new tag means you cleared the not-a-git-repo stage and hit a later one, such as create or start command. The Atlas worktree service names the next failing stage, so read the new tagged error name.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas with Ministral 3B: The $0.04 Housekeeping Model in 2026
Ministral 3B is the cheapest model Mistral sells: $0.04 / 1M input tokens and $0.04 / 1M output tokens across 128,000 tokens. Atlas small_model setup and limits.
Atlas with Command R 35B (Ollama): A RAG-Native Model for Retrieval-Heavy Work in 2026
Run Atlas on Command R 35B (Ollama): Cohere's 19GB RAG and tool-use model with a 128K context, free self-hosted. Check the research license before commercial use.
Atlas vs Kiro in 2026: Terminal Agent Compared to AWS's Spec-Driven IDE and CLI
Atlas vs Kiro in 2026. Kiro writes EARS-notation specs before code and charges credits; Atlas is a free, open source terminal agent with diff-before-write review.
Atlas with OpenAI o3-pro: The $20 / $80 Reasoning Escape Hatch (2026)
OpenAI o3-pro in Atlas costs $20 per Mtok input and $80 per Mtok output on a 200K context. A one shot escape hatch for hard problems, not an interactive default.
Atlas for Unreal Engine: Terminal-Native AI Coding for UCLASS and Build.cs in 2026
Atlas is a terminal-native AI coding agent for Unreal Engine C++ in 2026, where UCLASS macros, the reflection system, and Build.cs module rules are the real API.
Atlas for Next.js in 2026
Adopt Atlas, the terminal-native AI coding agent, for Next.js development in 2026. Enhance productivity across App Router, server components, and API routes with secure, reviewable AI assistance.
Atlas vs OpenHands: Terminal AI Coding Agents in 2026
Atlas and OpenHands comparison for 2026. Explore terminal-native TUI, self-hosting, code indexing, change review, and pricing models for AI coding agents.
Atlas for F#: A Terminal-Native AI Coding Agent for .fsproj Solutions in 2026
Atlas is a terminal-native AI coding agent for F# in 2026. It respects .fsproj file order, maps discriminated unions, runs dotnet test behind a prompt, and runs Fantomas.