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 SeaShell in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install SeaShellRelated guides
Atlas with Gemini 3.5 Flash in 2026
In 2026, Atlas developers can leverage Gemini 3.5 Flash for latency-optimized AI coding. It offers a 1M token context window and robust tool calling at $1.50/Mtok input.
Atlas vs Tabby: Terminal AI Coding Agents in 2026
Comparing Atlas and Tabby in 2026: Atlas offers terminal-native AI with explicit planning and diffing, while Tabby provides self-hosted GPU-based completion and a cloud agent.
Atlas with Claude Fable 5 in 2026
In 2026, Atlas developers can leverage Claude Fable 5 for complex coding tasks. Its 1M token context and high capability make it ideal for precise planning, despite its premium $10/$50 per Mtok cost.
Atlas with Mistral Small 24B (Ollama) in 2026
Drive Atlas, the terminal-native AI coding agent, with Mistral Small 24B (Ollama). Get reliable instruction following and structured output for free, self-hosted, with a 32K token context window.
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 in 2026
Explore Atlas with Qwen3-Next 80B-A3B Thinking, Alibaba's reasoning model. Leverage its 128K token context for deep planning in 2026, balancing $0.50 input costs with $6.00 output for detailed traces.
Atlas with IBM Granite Code 8B (Ollama) in 2026
Drive Atlas with IBM Granite Code 8B (Ollama) in 2026. Get a 125K token context window and enterprise-grade provenance, all self-hosted and free for your coding agent.