{"record":{"id":"d18259977fec6da7","repo":"FoundationAgents/MetaGPT","slug":"the-file-file-name-is-empty-please-use-the-ap","errorCode":null,"errorMessage":"The file '{file_name}' is empty. Please use the append method to add content.","messagePattern":"The file '(.+?)' is empty\\. Please use the append method to add content\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"metagpt/tools/libs/editor.py","lineNumber":887,"sourceCode":"        NOTE:\n            This tool is exclusive. If you use this tool, you cannot use any other commands in the current response.\n            If you need to use it multiple times, wait for the next turn.\n        \"\"\"\n        # FIXME: support replacing *all* occurrences\n\n        if to_replace == new_content:\n            raise ValueError(\"`to_replace` and `new_content` must be different.\")\n\n        # search for `to_replace` in the file\n        # if found, replace it with `new_content`\n        # if not found, perform a fuzzy search to find the closest match and replace it with `new_content`\n        file_name = self._try_fix_path(file_name)\n        with file_name.open(\"r\") as file:\n            file_content = file.read()\n\n        if to_replace.strip() == \"\":\n            if file_content.strip() == \"\":\n                raise ValueError(f\"The file '{file_name}' is empty. Please use the append method to add content.\")\n            raise ValueError(\"`to_replace` must not be empty.\")\n\n        if file_content.count(to_replace) > 1:\n            raise ValueError(\n                \"`to_replace` appears more than once, please include enough lines to make code in `to_replace` unique.\"\n            )\n        start = file_content.find(to_replace)\n        if start != -1:\n            # Convert start from index to line number\n            start_line_number = file_content[:start].count(\"\\n\") + 1\n            end_line_number = start_line_number + len(to_replace.splitlines()) - 1\n        else:\n\n            def _fuzzy_transform(s: str) -> str:\n                # remove all space except newline\n                return re.sub(r\"[^\\S\\n]+\", \"\", s)\n\n            # perform a fuzzy search (remove all spaces except newlines)","sourceCodeStart":869,"sourceCodeEnd":905,"githubUrl":"https://github.com/FoundationAgents/MetaGPT/blob/11cdf466d042aece04fc6cfd13b28e1a70341b1f/metagpt/tools/libs/editor.py#L869-L905","documentation":"Raised by Editor._edit_file_by_replace when to_replace is empty/whitespace-only AND the target file's content is also empty after stripping. The tool detects the caller attempted a 'match empty string' replace against an empty file and steers them to the append API, which is the correct way to add content to an empty file.","triggerScenarios":"editor.edit_file_by_replace(path, to_replace='', new_content=c) on a zero-byte or whitespace-only file (e.g. one just created by create_file, which writes a single newline).","commonSituations":"Agents immediately 'replacing' into freshly created files; create_file writes '\\n' so a brand-new file is empty-by-strip and hits this path; bootstrap flows that should append instead.","solutions":["Use the append mode (or insert at line 1) to add initial content to an empty file","Write initial content at creation time rather than replace-after-create"],"exampleFix":"// before\neditor.create_file('a.py')\neditor.edit_file_by_replace('a.py', to_replace='\\n', new_content='x = 1\\n')  # ValueError: file is empty\n\n// after\neditor.create_file('a.py')\neditor.append_file('a.py', 'x = 1\\n')  # or write content via insert at line 1","handlingStrategy":"validation","validationCode":"content = Path(file_name).read_text()\nif content.strip() == '':\n    editor.append_file(file_name, new_content)  # correct API for empty files\nelse:\n    editor.edit_file_by_replace(file_name, to_replace, new_content)","typeGuard":"def file_is_empty(p: str) -> bool:\n    return Path(p).read_text().strip() == ''","tryCatchPattern":"try:\n    editor.edit_file_by_replace(path, to_replace, new_content)\nexcept ValueError as e:\n    if 'is empty' in str(e):\n        editor.append_file(path, new_content)\n    else:\n        raise","preventionTips":["Remember create_file writes a single newline — new files are 'empty' for replace","Bootstrap new files with append/insert, then switch to replace","Branch on file emptiness in your write helper"],"tags":["editor","replace","empty-file","metagpt"],"backgroundTag":null,"analyzedSha":"11cdf466d042aece04fc6cfd13b28e1a70341b1f","analyzedAt":"2026-08-14T23:20:02.994Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}