Atlas refuses to remove a worktree and raises a Git.WorktreeError with forceRequired set to true because git reported that the worktree contains modified or untracked files. The fix is to commit or stash the changes inside the worktree and then remove it again, or to accept the loss and remove with force, which is exactly what the forceRequired flag is signalling. Check the `directory` field on the error to confirm which worktree is dirty.
Why does Atlas set forceRequired on a worktree removal
Atlas sets forceRequired on a Git.WorktreeError when the operation is remove and git's message matches 1 of 2 patterns, "contains modified or untracked files" or "is dirty". Atlas Git.worktree runs the git command, sees the non-zero exit, and raises the error with that flag so the UI can offer a force path.
The forceRequired flag is not Atlas guessing. Atlas runs the real git worktree command, reads git's own stderr message, and pattern-matches it against the two dirty-tree phrasings git uses. When the match hits on a remove operation, Atlas marks the error forceRequired, which tells the calling surface that a force removal is the available escape hatch. The message you see in the error is git's, verbatim, not a rewrite by Atlas. That is why quoting it back into a search box lands you here: the string "contains modified or untracked files" comes straight from git.
How to remove a dirty Atlas worktree safely
The safe fix for a dirty Atlas worktree is 1 step: commit or stash the changes inside the worktree, then remove it again. Once the worktree is clean, git stops reporting "contains modified or untracked files" and the removal succeeds without any force flag at all.
Commit if the work is worth keeping in history, and stash if it is a scratch state you want to revisit. Either way, do the work inside the worktree named by the `directory` field on the WorktreeError, not in the main checkout, because those are different working trees and a clean main repo tells you nothing about the worktree git is complaining about. Untracked files count as dirty here too, so a stash that skips untracked files may leave the tree dirty and the removal will fail again with the same message.
When to remove an Atlas worktree with force
Remove an Atlas worktree with force when you have decided the uncommitted work inside it is disposable. The forceRequired flag on the Git.WorktreeError signals exactly that path, and taking it in 2026 still means accepting the loss of the modified or untracked files git refused to discard on its own.
Be honest about the caveat, because forcing is destructive. Git refused the plain removal precisely to stop you from throwing away changes you might not know about, and Atlas surfaced forceRequired rather than forcing silently. Before you force, look at what is actually in the worktree. Atlas snapshots file changes as git patches so edits can be diffed and rolled back, and Atlas computes a unified diff for every file edit and surfaces it for approval before writing, but neither of those helps for untracked scratch files you never asked Atlas to touch. Force only when you have looked.
How to tell which Atlas worktree is dirty
Check the `directory` field on the Atlas Git.WorktreeError to confirm which worktree is dirty. The WorktreeError carries 3 pieces of context: the operation, the directory, and git's message, so the directory field names the exact working tree git refused to remove.
Reading the directory field first saves a lot of wasted effort, especially when Atlas fans out work to subagents that can run in the foreground or in parallel background sessions and several worktrees exist at once. The clean tree you are looking at in your editor may not be the one git is refusing to remove. Open the path named in the directory field, inspect its status there, and commit or stash inside that path. Only then retry the removal. Fixing the wrong worktree is the single most common reason the same WorktreeError comes back unchanged.
Is the Atlas WorktreeError always about a dirty tree
No. Atlas raises the same Git.WorktreeError type for creation failures, and in that case the error carries operation: "create" rather than remove. Read the operation field first, because forceRequired is set on exactly 1 operation, remove, and only when git's message says the worktree is dirty.
The WorktreeError is a shared shape across git worktree operations in Atlas, so seeing it does not by itself tell you what went wrong. A create failure and a dirty-remove failure arrive as the same type, distinguished by the operation field and by whether forceRequired is set. Committing or stashing does nothing for a create failure, and forcing is not even offered there. Read operation, then directory, then git's message, in that order. The three fields together tell you exactly which git invocation failed, where, and why.
How to verify the worktree removal fix worked
Verify the Atlas worktree fix by re-running the removal after committing or stashing inside the directory named on the WorktreeError. Success means git exits 0, no Git.WorktreeError is raised, forceRequired never appears, and git no longer reports that the worktree contains modified or untracked files.
If the same WorktreeError comes back with forceRequired still true, the worktree named in the directory field is still dirty, and untracked files are the usual survivor: a plain stash leaves them behind. If a WorktreeError comes back but forceRequired is now absent, look at the operation field, because you may be seeing a different failure mode entirely. And if the removal succeeds, git's own message disappears from the Atlas output, which is the clean signal that the tree was actually cleaned rather than force-discarded.
How to fix it
- 01Commit or stash the changes inside the worktree, then remove it again.
- 02Or accept the loss and remove with force, which is exactly what forceRequired is signalling.
- 03Check the `directory` field on the WorktreeError to confirm which worktree is dirty.
- 04For creation failures, the same error type carries operation: "create", so read the operation before assuming it is a dirty tree.
Frequently asked questions
- How do I fix an Atlas worktree that will not remove because it is dirty?
- Commit or stash the changes inside the worktree, then remove it again. Git refuses removal when the worktree contains modified or untracked files, and Atlas surfaces that as a Git.WorktreeError with forceRequired set to true.
- What does forceRequired mean on an Atlas WorktreeError?
- forceRequired means Atlas matched git's message against "contains modified or untracked files" or "is dirty" on a remove operation. It signals that a force removal is available, at the cost of losing the uncommitted work.
- Is it safe to force remove an Atlas worktree?
- Forcing is destructive. Git refused the plain removal to protect modified or untracked files, so force only after you have inspected the worktree named in the error's `directory` field and decided the work is disposable.
- Which worktree is Atlas complaining about?
- Check the `directory` field on the Git.WorktreeError. Atlas carries the operation, the directory, and git's message on the error, and the directory field names the exact worktree that git refused to remove.
- Does the Atlas WorktreeError always mean a dirty worktree?
- No. The same error type carries operation: "create" for creation failures, so read the operation before assuming it is a dirty tree. forceRequired is only ever set when the operation is remove.
- Why does Atlas still say the worktree is dirty after I stashed?
- Untracked files count as dirty. A stash that leaves untracked files behind will still trip git's "contains modified or untracked files" check, so the Atlas removal fails again with the same WorktreeError.
- Where does the Atlas worktree error message come from?
- The message is git's own. Atlas Git.worktree runs the git command and, on a non-zero exit, raises WorktreeError carrying the operation, the directory, and git's message verbatim.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas with Gemini 3.5 Flash: The May 2026 Latency Tier That Keeps 1M Context
Gemini 3.5 Flash in Atlas: the May 2026 release keeps the full 1,048,576 token window at $1.50 / $9 per Mtok, with reasoning and tool calling enabled.
Atlas vs Tabby: Terminal AI Coding Agents in 2026
Atlas and Tabby comparison for 2026. Atlas offers terminal-native TUI with permission-gated tools and diff review. Tabby provides self-hosted GPU completion and a cloud agent.
Atlas with Claude Fable 5: Plan Mode Model Guide for 2026
Claude Fable 5 is Anthropic's premium June 2026 model at $10 / $50 per Mtok with a 1M window. Use it for one expensive Atlas planning pass, then drop back down.
Atlas with Mistral Small 24B (Ollama): The Single-GPU Commercial Pick for 2026
Run Atlas on Mistral Small 24B (Ollama): 14GB weights, 32K context, Apache 2.0, free self-hosted. Setup, the 32K vs 128K tag trap, and when a coder beats it.
Atlas for Godot: Terminal-Native AI Coding for GDScript and the Node Tree in 2026
Atlas is a terminal-native AI coding agent for Godot in 2026, working across GDScript, the node tree, and signals, where scene structure is half the program.
Review a Pull Request with Atlas (2026 Workflow)
How to review a pull request with Atlas in 2026: bash produces the raw patch, read pulls whole files, the lsp tool's findReferences checks callers the diff never shows.
Atlas with Qwen3-Next 80B-A3B Thinking: The Reasoning Tier in 2026
Drive Atlas with Qwen3-Next 80B-A3B Thinking: a reasoning trace over 128K tokens (131,072) of context at $0.50 per Mtok input and $6.00 per Mtok output.
Atlas with IBM Granite Code 8B (Ollama): 125K Context on 4.6GB in 2026
IBM Granite Code 8B (Ollama) gives Atlas a 125K tokens window from a 4.6GB download, Free (self-hosted), with enterprise licensing. Setup, tags, and tradeoffs.