{"record":{"id":"89d03d4c1fec9c57","repo":"FoundationAgents/MetaGPT","slug":"line-number-must-be-between-1-and-total-lines","errorCode":null,"errorMessage":"Line number must be between 1 and {total_lines}","messagePattern":"Line number must be between 1 and (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"metagpt/tools/libs/editor.py","lineNumber":304,"sourceCode":"        Args:\n            path: str: The path to the file to open, preferred absolute path.\n            line_number: int | None = 1: The line number to move to. Defaults to 1.\n            context_lines: int | None = 100: Only shows this number of lines in the context window (usually from line 1), with line_number as the center (if possible). Defaults to 100.\n        \"\"\"\n        if context_lines is None:\n            context_lines = self.window\n\n        path = self._try_fix_path(path)\n\n        if not path.is_file():\n            raise FileNotFoundError(f\"File {path} not found\")\n\n        self.current_file = path\n        with path.open() as file:\n            total_lines = max(1, sum(1 for _ in file))\n\n        if not isinstance(line_number, int) or line_number < 1 or line_number > total_lines:\n            raise ValueError(f\"Line number must be between 1 and {total_lines}\")\n        self.current_line = line_number\n\n        # Override WINDOW with context_lines\n        if context_lines is None or context_lines < 1:\n            context_lines = self.window\n\n        output = self._cur_file_header(path, total_lines)\n        output += self._print_window(path, self.current_line, self._clamp(context_lines, 1, 2000))\n        self.resource.report(path, \"path\")\n        return output\n\n    def goto_line(self, line_number: int) -> str:\n        \"\"\"Moves the window to show the specified line number.\n\n        Args:\n            line_number: int: The line number to move to.\n        \"\"\"\n        self._check_current_file()","sourceCodeStart":286,"sourceCodeEnd":322,"githubUrl":"https://github.com/FoundationAgents/MetaGPT/blob/11cdf466d042aece04fc6cfd13b28e1a70341b1f/metagpt/tools/libs/editor.py#L286-L322","documentation":"Raised by Editor.open_file when the line_number argument is not an int, is below 1, or exceeds the file's total line count. The editor counts the file's lines first and requires line_number to land within [1, total_lines] before it positions the window there.","triggerScenarios":"editor.open_file(path, line_number=0), line_number=-3, line_number=500 on a 120-line file, or line_number='10' (a string, failing the isinstance int check). Also line_number=1 on an empty file is fine (total is clamped to 1), but any value >1 on a 1-line file fails.","commonSituations":"LLM agents emitting 0-based line numbers or hallucinated large line numbers; off-by-one when translating an editor/IDE cursor position; passing line numbers as strings from JSON tool arguments.","solutions":["Clamp line_number to 1..total_lines before the call (count lines yourself, or just use the default line_number=1)","Coerce string arguments to int before calling","For 0-based line numbers from another tool, add 1 before passing"],"exampleFix":"// before\neditor.open_file(path, line_number=0)  # ValueError\n\n// after\nline_number = max(1, int(line_number))\neditor.open_file(path, line_number=line_number)","handlingStrategy":"validation","validationCode":"line_number = max(1, int(line_number))\ntotal = sum(1 for _ in open(path))\nline_number = min(line_number, total)\neditor.open_file(path, line_number=line_number)","typeGuard":"def valid_line(n, total: int) -> bool:\n    return isinstance(n, int) and 1 <= n <= total","tryCatchPattern":"try:\n    editor.open_file(path, line_number=n)\nexcept ValueError:\n    editor.open_file(path)  # fall back to default line 1","preventionTips":["This API is 1-based; convert 0-based indices by adding 1","Coerce numeric strings from JSON tool args to int before calling","When in doubt, omit line_number (defaults to 1) and navigate with goto_line after"],"tags":["editor","validation","line-numbers","metagpt"],"backgroundTag":null,"analyzedSha":"11cdf466d042aece04fc6cfd13b28e1a70341b1f","analyzedAt":"2026-08-14T23:20:02.994Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}