# Atlas edit error: oldString cannot be empty when editing an existing file > Supply the exact text to replace as oldString, or call the write tool if you really intend to replace the whole file. 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. ## Symptom The edit tool fails with: oldString cannot be empty when editing an existing file. Provide the exact text to replace, or use write for an intentional full-file replacement. ## Cause An empty oldString is how edit creates a new file. When the target already exists, Atlas refuses to interpret that as a full-file overwrite and tells you to use write instead. ## Fix 1. Supply the exact text you want replaced as oldString, copied verbatim from the file. 2. Or call the write tool if you really intend to replace the whole file rather than a region of it. 3. Check the path. An empty oldString on a path you thought was new means the file already exists, which is often the real finding. 4. Note 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. 5. Re-run the edit with a non-empty oldString, or the write call, and confirm the change is surfaced as a diff for approval. ## 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. ## FAQ ### 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. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/edit-empty-oldstring-on-existing-file Source of truth: aeo_pages row `/resources/troubleshooting/edit-empty-oldstring-on-existing-file` (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.