{"record":{"id":"9abbefb704854e34","repo":"zylon-ai/private-gpt","slug":"unable-to-insert-text","errorCode":null,"errorMessage":"Unable to insert text","messagePattern":"Unable to insert text","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"private_gpt/components/tools/builders/text_editor_tool_builder.py","lineNumber":218,"sourceCode":"            ),\n        )\n\n    async def build_insert_tool(\n        self,\n        config: CodeExecutionSessionConfig,\n        name: str = TEXT_EDITOR_INSERT_TOOL_NAME,\n        type: str = TEXT_EDITOR_INSERT_TOOL_NAME + \"_v1\",\n        description: str = TEXT_EDITOR_INSERT_TOOL_FN.metadata.description,\n    ) -> ToolSpec:\n        async def insert(\n            path: str,\n            insert_line: int,\n            new_str: str,\n        ) -> list[ResultContentBlockType]:\n            session = await self._session(config)\n            result = await session.insert(path, insert_line, new_str)\n            if not result.success:\n                raise RuntimeError(result.error or \"Unable to insert text\")\n            output = _truncated(\n                result.output, self._settings.code_execution.max_output_bytes\n            )\n            inserted_lines = len(new_str.splitlines())\n            return [\n                TextEditorCodeExecutionStrReplaceResultBlock(\n                    old_start=insert_line,\n                    new_start=insert_line,\n                    new_lines=inserted_lines,\n                    lines=[output],\n                )\n            ]\n\n        return ToolSpec.from_defaults(\n            name=name,\n            type=type,\n            runtime=\"server\",\n            event_adapter=TextEditorCodeExecutionEventAdapter,","sourceCodeStart":200,"sourceCodeEnd":236,"githubUrl":"https://github.com/zylon-ai/private-gpt/blob/4a030776a31a901ad80b1bf4d7faa2c1a367efbb/private_gpt/components/tools/builders/text_editor_tool_builder.py#L200-L236","documentation":"Raised by the text-editor insert tool when the underlying edit session reports a failed insert operation (session.insert returns success=False). The message is either the session's error detail or the generic 'Unable to insert text' fallback when the session gave no reason. It means the edit itself was rejected, not that the tool wiring failed.","triggerScenarios":"Calling the insert tool (TEXT_EDITOR_INSERT_TOOL_NAME) with a path that does not exist or is not readable/writable by the sandboxed session, an insert_line outside the file's line range, or a session backend (e.g. code-execution sandbox) that failed to apply the edit and set result.success=False with result.error empty.","commonSituations":"Agent/LLM hallucinating a file path or line number; permission mismatch between the tool process and the file; file modified concurrently so the session's view is stale; sandbox restrictions blocking writes.","solutions":["Check result.error / server logs for the underlying session failure before the generic message was substituted","Verify the target path exists and the tool process has read/write permission on it","Validate insert_line against the current file (0 <= insert_line <= line_count) before invoking the tool","Re-read the file (view tool) to refresh line numbers, then retry the insert"],"exampleFix":"# before\nresult = await session.insert(path, insert_line, new_str)\n# after\ncontent = await session.view(path, 0)\nmax_line = len(content.output.splitlines())\nif not (0 <= insert_line <= max_line):\n    raise ValueError(f\"insert_line {insert_line} out of range 0..{max_line}\")\nresult = await session.insert(path, insert_line, new_str)","handlingStrategy":"try-catch","validationCode":"from pathlib import Path\n\np = Path(path)\nassert p.is_file(), f\"{path} is not an existing file\"\nline_count = len(p.read_text().splitlines())\nassert 0 <= insert_line <= line_count, f\"insert_line {insert_line} out of range 0..{line_count}\"","typeGuard":null,"tryCatchPattern":"try:\n    blocks = await insert(path, insert_line, new_str)\nexcept RuntimeError as e:\n    if \"Unable to insert text\" in str(e):\n        # re-view the file, correct path/line, retry once with corrected args\n        raise\n    raise","preventionTips":["Always view/read the file through the same session before editing so line numbers match","Validate path existence and line range client-side before calling insert","Surfaced result.error whenever present instead of relying on the generic message"],"tags":["text-editor","file-io","tool","runtime-error"],"backgroundTag":null,"analyzedSha":"4a030776a31a901ad80b1bf4d7faa2c1a367efbb","analyzedAt":"2026-08-15T03:51:26.951Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}