Atlas rejects an empty oldString on an existing file because an empty oldString is how the edit tool creates a new file, and when the target already exists Atlas refuses to reinterpret that as a full-file overwrite, so the fix is to supply the exact text you want replaced as oldString, or to call the write tool if you really do intend to replace the whole file. The error says both options out loud: Provide the exact text to replace, or use write for an intentional full-file replacement. There is a third thing worth checking. An empty oldString on a path you believed was new means the file already exists, so confirm the path before assuming the tool is wrong.
Why does Atlas reject an empty oldString on an existing file
Atlas rejects an empty oldString on an existing file because that input already means exactly 1 thing in the edit tool: create a new file. When the target already exists, Atlas will not reinterpret the same signal as a full-file overwrite, so it raises the error and names the 2 safe alternatives instead of guessing.
The design is a deliberate refusal to overload one input with two destructive meanings. Empty oldString on a path with no file is unambiguous and useful, because it is how the edit tool scaffolds something new. Empty oldString on a path that does have a file could plausibly mean prepend, or replace everything, or create and clobber, and Atlas does not pick one on your behalf. Instead it names the two safe interpretations in the error text: Provide the exact text to replace, or use write for an intentional full-file replacement. Both are explicit. Neither can silently destroy a file you forgot was there.
How to fix an empty oldString error in Atlas edit
Fix the Atlas empty oldString error by choosing between the 2 options the error itself names. To change part of the file, supply the exact text you want replaced as oldString. To replace the entire file contents, call the write tool. Atlas will not infer which of the 2 you meant.
Most of the time the first option is the right one. Read the file, copy the region you intend to change verbatim, and pass that region as oldString, and the edit proceeds normally with Atlas computing a unified diff for the file edit and surfacing it for approval before writing. The second option is correct when you genuinely have new whole-file contents, such as a regenerated config or a rewritten module, and reaching for write states that intent plainly. Naming the intent is the fix. There is no flag that makes an empty oldString mean overwrite.
When an empty oldString error means the file already exists
An empty oldString error in Atlas is often a discovery rather than a defect. Passing an empty oldString is the 1 documented way to create a new file, so if the edit tool reports that the file already exists, then a file you believed was absent is present at that path. Check the path before you touch anything else.
Treat the message as free information about the state of your working tree. An agent scaffolding a new module with an empty oldString expects a clean path, and the error means that expectation was wrong. Common explanations: the file was created earlier in the same session, the path collides with an existing module you forgot about, or the path is subtly different from the one you intended and points at something real. Investigate before you convert the call into a write, because writing over a file you did not know existed is precisely the outcome the guard just prevented.
Why the Atlas empty oldString guard fires in both the tool and the helper
The Atlas empty oldString guard is implemented in 2 places on purpose: the edit tool itself, and the pure `replace` helper. Because the check is duplicated, the rejection fires on both the tool path and the unit path, and no call route turns an empty oldString into a full-file overwrite.
Duplicating the guard makes the invariant structural rather than incidental. A check that lives only in the tool wrapper can be bypassed by any caller that reaches the underlying helper directly, and an invariant that important should not depend on which entry point happened to be used. Because the pure `replace` helper repeats the check, empty oldString plus an existing file is rejected consistently. The practical consequence for you is simple and worth stating plainly: there is no clever alternate call path that turns an empty oldString into a full-file overwrite. Use write when a full-file overwrite is what you want.
How to verify the Atlas edit or write landed correctly
Verify by running the corrected call. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so review that diff and confirm it touches only the region you meant. Atlas also snapshots file changes as git patches, which means either of the 2 corrected calls, edit or write, can be rolled back.
Read whichever surface Atlas gives you before approving. For an edit, confirm the hunk touches the region you meant and only that region. For a write, confirm you genuinely intended to discard the previous contents of that path, since a write is exactly the destructive operation the empty oldString guard was protecting you from performing by accident. If you converted the call to a write only because the empty oldString was rejected, stop and reconsider, because an accidental overwrite of a file you did not know existed is the specific failure this error was designed to prevent.
How to fix it
- 01Supply the exact text you want replaced as oldString, copied verbatim from the file.
- 02Or call the write tool if you really intend to replace the whole file rather than a region of it.
- 03Check the path. An empty oldString on a path you thought was new means the file already exists, which is often the real finding.
- 04Note that the same guard exists in the pure `replace` helper, so it fires in both the tool and its unit path, and there is no route around it.
- 05Re-run the edit with a non-empty oldString, or the write call, and confirm the change is surfaced as a diff for approval.
Frequently asked questions
- what does oldString cannot be empty when editing an existing file mean in Atlas
- An empty oldString is how the Atlas edit tool creates a new file. When the target already exists, Atlas refuses to reinterpret that as a full-file overwrite and asks you to supply the exact text to replace, or to use write instead.
- how do I replace an entire file in Atlas
- Use the write tool. The Atlas edit tool will not accept an empty oldString on an existing file as an overwrite instruction, because write is the explicit way to state that you intend a full-file replacement.
- how do I create a new file with Atlas edit
- Pass an empty oldString. An empty oldString on a path with no existing file is how the Atlas edit tool creates a new file. On a path that already has a file, the same input is rejected.
- why does Atlas say my new file already exists
- Because it does. An empty oldString is a create-file signal, so the rejection means a file is present at that path. Check whether the file was created earlier in the session or whether the path is subtly wrong.
- can I force Atlas edit to overwrite a file with an empty oldString
- No. The guard exists in the edit tool and is repeated in the pure `replace` helper, so it fires in both the tool and its unit path. There is no call route that turns an empty oldString into a full-file overwrite.
- should I use edit or write in Atlas
- Use edit to change a bounded region of a file, supplying the exact text to replace as oldString. Use write when you intend to replace the whole file contents. Atlas will not infer which one you meant from an empty oldString.
- does the Atlas empty oldString error change my file
- No. Atlas rejects the call before any write happens, which is why the guard exists at all. The file at that path is exactly as it was, so investigate the path before converting the call into a write.
Try SeaShell in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install SeaShellRelated guides
Onboard to an Unfamiliar Codebase with Atlas in 2026
How to onboard to an unfamiliar codebase with Atlas in 2026: use codebase_search, glob, read, lsp, task, and todowrite to build a mental model fast.
Atlas vs Zed: Terminal AI Coding Agents in 2026
Comparing Atlas, the terminal-native AI coding agent, with Zed, the GPU-accelerated collaborative editor, for developers in 2026. Evaluate their AI models, workflow, and safety features.
Atlas with Llama 4 Maverick in 2026
Explore Llama 4 Maverick's 1M token context and open weights for Atlas in 2026. Understand its cost-effectiveness and tradeoffs for terminal-native AI coding.
Atlas with Command R 35B (Ollama) in 2026
Explore Atlas with Command R 35B (Ollama) in 2026. This free, self-hosted model offers a 128K context window, excelling at RAG and tool use for your terminal-native AI coding agent.
Atlas with North Mini Code in 2026
Explore Atlas with North Mini Code, Cohere's 2026 code-specialist model. Benefit from its 256,000 token context, 64,000 token output, and $0 pricing for large refactors.
Atlas with Groq (gateway) in 2026
In 2026, Atlas developers can leverage Groq (gateway) for unparalleled token throughput and cost-effective open models like GPT-OSS 120B and Llama 3.1 8B, ideal for rapid agent loops.
Atlas with StarCoder2 15B (Ollama) in 2026
Drive Atlas with StarCoder2 15B (Ollama) in 2026. This free, self-hosted model offers transparent training data provenance and strong multi-language support for your coding agent.
Atlas for Symfony in 2026
Atlas is a terminal-native AI coding agent for Symfony in 2026. It reads autowired services and Doctrine mappings, and shows migration SQL before anything runs.