# Atlas WorktreeNotGitError: worktree operations fail outside a git repo > Confirm the project directory is a git repository by running `git status` inside it, then initialize the repo before retrying the Atlas worktree operation. 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. ## Symptom Creating or listing a worktree in Atlas fails with WorktreeNotGitError, WorktreeCreateFailedError, WorktreeListFailedError, or WorktreeStartCommandFailedError. The API returns the failure as a WorktreeError response. ## Cause 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. The API maps these to a WorktreeError response, so the tag tells you which stage failed. ## Fix 1. Confirm the project directory is a git repository; run `git status` inside it. 2. Initialize the repo first. Atlas can do this, and it throws "Git is not installed" if git is absent. 3. If the failure is WorktreeStartCommandFailedError, the worktree was created but your configured start command failed; fix that command. 4. Read the tagged error name in the response to tell a create failure from a list failure. ## 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. ## FAQ ### 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. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/worktree-not-a-git-repo Source of truth: aeo_pages row `/resources/troubleshooting/worktree-not-a-git-repo` (segment: Troubleshooting) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.