{"record":{"id":"f007d8a8520f3c9f","repo":"FoundationAgents/MetaGPT","slug":"invalid-line-number-start-line-numbers-must-be","errorCode":null,"errorMessage":"Invalid line number: {start}. Line numbers must be between 1 and {len(lines)} (inclusive).","messagePattern":"Invalid line number: (.+?)\\. Line numbers must be between 1 and (.+?) \\(inclusive\\)\\.","errorType":"exception","errorClass":"LineNumberError","httpStatus":null,"severity":"error","filePath":"metagpt/tools/libs/editor.py","lineNumber":427,"sourceCode":"            n_added_lines: int: The number of lines added to the file.\n\n        Raises:\n            LineNumberError: If the start line number is invalid.\n        \"\"\"\n        inserted_lines = [content + \"\\n\" if not content.endswith(\"\\n\") else content]\n        if len(lines) == 0:\n            new_lines = inserted_lines\n        elif start is not None:\n            if len(lines) == 1 and lines[0].strip() == \"\":\n                # if the file with only 1 line and that line is empty\n                lines = []\n\n            if len(lines) == 0:\n                new_lines = inserted_lines\n            else:\n                new_lines = lines[: start - 1] + inserted_lines + lines[start - 1 :]\n        else:\n            raise LineNumberError(\n                f\"Invalid line number: {start}. Line numbers must be between 1 and {len(lines)} (inclusive).\"\n            )\n\n        content = \"\".join(new_lines)\n        n_added_lines = len(inserted_lines)\n        return content, n_added_lines\n\n    @staticmethod\n    def _edit_impl(lines, start, end, content):\n        \"\"\"Internal method to handle editing a file.\n\n        REQUIRES (should be checked by caller):\n            start <= end\n            start and end are between 1 and len(lines) (inclusive)\n            content ends with a newline\n\n        Args:\n            lines: list[str]: The lines in the original file.","sourceCodeStart":409,"sourceCodeEnd":445,"githubUrl":"https://github.com/FoundationAgents/MetaGPT/blob/11cdf466d042aece04fc6cfd13b28e1a70341b1f/metagpt/tools/libs/editor.py#L409-L445","documentation":"Raised by Editor._insert_impl when inserting into a non-empty file but start is None, so there is no anchor line to insert at. The insert algorithm needs a 1-based line position; with an empty file it can place content outright, but with existing lines and no start it cannot decide where to insert, so it raises LineNumberError.","triggerScenarios":"Calling the insert path (insert_content_at / _edit_file_impl with is_insert=True) without a line number on a file that has content; passing start=None explicitly; a caller bug where the start argument is dropped.","commonSituations":"Agent tool calls that omit the line parameter when inserting; wrappers with defaulted start=None forwarding None into insert.","solutions":["Always supply a start line (1..len(lines)) when inserting into a non-empty file","To add at the end, use the append mode instead of insert with no start","For a truly empty file, either keep it empty-then-insert (allowed) or create content directly"],"exampleFix":"// before\neditor.insert_content_at('new line')  # start omitted on non-empty file\n\n// after\neditor.insert_content_at('new line', line_number=len(lines) + 1)  # or use append","handlingStrategy":"validation","validationCode":"lines = editor.current_file.read_text().splitlines()\nstart = len(lines) + 1 if start is None else start\nassert 1 <= start <= max(1, len(lines) + 1)\n# then perform insert via editor API with explicit line_number","typeGuard":"def has_insert_anchor(start, n_lines: int) -> bool:\n    return start is not None and 1 <= start <= n_lines + 1","tryCatchPattern":"try:\n    result = editor.insert_content_at(content, line_number=start)\nexcept LineNumberError:\n    result = editor.append_file(content)  # append when no anchor fits","preventionTips":["Always pass an explicit line_number when inserting into non-empty files","Use append for end-of-file additions instead of insert-without-start","Unit-test the insert path with empty and one-line files"],"tags":["editor","line-numbers","insert","metagpt"],"backgroundTag":null,"analyzedSha":"11cdf466d042aece04fc6cfd13b28e1a70341b1f","analyzedAt":"2026-08-14T23:20:02.994Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}