{"record":{"id":"c231e02560e71c45","repo":"oraios/serena","slug":"unhandled-document-change-kind-change-please-r","errorCode":null,"errorMessage":"Unhandled document change kind: {change}; Please report to Serena developers.","messagePattern":"Unhandled document change kind: (.+?); Please report to Serena developers\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/serena/code_editor.py","lineNumber":363,"sourceCode":"            new_abs_path = os.path.join(self._code_editor.project_root, self._new_relative_path)\n            os.rename(old_abs_path, new_abs_path)\n\n    def _workspace_edit_to_edit_operations(self, workspace_edit: ls_types.WorkspaceEdit) -> list[\"LanguageServerCodeEditor.EditOperation\"]:\n        operations: list[LanguageServerCodeEditor.EditOperation] = []\n\n        if \"changes\" in workspace_edit:\n            for uri, edits in workspace_edit[\"changes\"].items():\n                operations.append(self.EditOperationFileTextEdits(self, uri, edits))\n\n        if \"documentChanges\" in workspace_edit:\n            for change in workspace_edit[\"documentChanges\"]:\n                if \"textDocument\" in change and \"edits\" in change:\n                    operations.append(self.EditOperationFileTextEdits(self, change[\"textDocument\"][\"uri\"], change[\"edits\"]))\n                elif \"kind\" in change:\n                    if change[\"kind\"] == \"rename\":\n                        operations.append(self.EditOperationRenameFile(self, change[\"oldUri\"], change[\"newUri\"]))\n                    else:\n                        raise ValueError(f\"Unhandled document change kind: {change}; Please report to Serena developers.\")\n                else:\n                    raise ValueError(f\"Unhandled document change format: {change}; Please report to Serena developers.\")\n\n        return operations\n\n    def _apply_workspace_edit(self, workspace_edit: ls_types.WorkspaceEdit) -> int:\n        \"\"\"\n        Applies a WorkspaceEdit\n\n        :param workspace_edit: the edit to apply\n        :return: number of edit operations applied\n        \"\"\"\n        operations = self._workspace_edit_to_edit_operations(workspace_edit)\n        for operation in operations:\n            operation.apply()\n        return len(operations)\n\n    def rename_symbol(self, name_path: str, relative_path: str, new_name: str) -> str:","sourceCodeStart":345,"sourceCodeEnd":381,"githubUrl":"https://github.com/oraios/serena/blob/7fcbca7e62555ec2287ddb2f083caee805848ea6/src/serena/code_editor.py#L345-L381","documentation":"When converting an LSP WorkspaceEdit into local edit operations, serena handles text edits and 'rename' kind changes. Any other documentChange kind (e.g. 'create', 'delete', 'copy' from newer LSP specs) is unhandled and raises ValueError asking for a bug report — the rename would otherwise be applied incorrectly or partially.","triggerScenarios":"A language server returns a WorkspaceEdit whose documentChanges include a change with `kind` set to something other than \"rename\" (create/delete/copy), e.g. after a rename refactoring that also creates/deletes files, using an LS with extended LSP 3.17 features.","commonSituations":"Using a language server that emits file create/delete operations alongside renames (e.g. move-class refactorings); applying an edit produced by one tool through serena's editor; LSP version mismatches.","solutions":["Report the issue to Serena developers with the language server name/version and the operation that triggered it (the message asks for this).","Avoid the specific LS refactoring that emits the unsupported kind; use a plain rename or manual edits.","Upgrade serena — support for additional kinds may have been added.","Check/switch the language server version to one that only emits text edits and renames for this operation."],"exampleFix":"// before\nresult = editor.apply(...)  # LS emits kind:'delete' -> ValueError\n// after\n# upgrade serena first\npip install -U serena-agent\n# if it persists, report to https://github.com/oraios/serena with the LS name/version","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    editor.apply(edit_call)\nexcept ValueError as e:\n    if 'Unhandled document change kind' in str(e):\n        log.error('LS emitted unsupported WorkspaceEdit kind; report to serena devs with LS name/version: %s', e)\n        # fall back to manual file operations for the affected files","preventionTips":["Pin a language server version known to emit only text edits and renames for your refactorings.","Keep serena updated; new kinds get support over time.","File a bug with the serena project when you hit this — the message explicitly requests it.","Test complex refactorings (move/rename across files) on a scratch copy before running on real code."],"tags":["language-server","lsp","workspace-edit","unhandled-case"],"backgroundTag":"unhandled-lsp-workspace-edit-kind","analyzedSha":"7fcbca7e62555ec2287ddb2f083caee805848ea6","analyzedAt":"2026-08-29T00:04:09.619Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}