{"record":{"id":"62767ac07ce48a54","repo":"oraios/serena","slug":"unhandled-document-change-format-change-please","errorCode":null,"errorMessage":"Unhandled document change format: {change}; Please report to Serena developers.","messagePattern":"Unhandled document change format: (.+?); Please report to Serena developers\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/serena/code_editor.py","lineNumber":365,"sourceCode":"\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:\n        \"\"\"\n        Renames a symbol, file, or directory throughout the codebase.","sourceCodeStart":347,"sourceCodeEnd":383,"githubUrl":"https://github.com/oraios/serena/blob/7fcbca7e62555ec2287ddb2f083caee805848ea6/src/serena/code_editor.py#L347-L383","documentation":"Serena's _workspace_edit_to_edit_operations converts an LSP WorkspaceEdit into local edit operations. Each TextDocumentEdit/change entry is dispatched by shape; a change that is neither a text edit, nor has a recognizable 'kind' like 'rename', falls into this ValueError. It exists because the language server emitted a document-change format Serena does not implement, and the message asks for a bug report.","triggerScenarios":"Calling rename_symbol (or any tool that applies a WorkspaceEdit via _apply_workspace_edit) when the language server returns an edit whose change object has a 'kind' field other than 'rename' (e.g. 'create', 'delete', 'copy' from ResourceOperation), or an entirely unrecognized change shape.","commonSituations":"Using a language server (or newer server version) that returns resource operations like create/delete in rename results; custom MCP clients injecting non-standard WorkspaceEdit payloads; Serena version lagging behind LSP features of the server.","solutions":["Report the issue to the Serena developers with the full change payload from the message","Check for a Serena update that adds support for the change kind your language server emits","Switch to a language server whose rename results only contain TextDocumentEdits","Wrap the operation and fall back to applying edits manually via the raw WorkspaceEdit"],"exampleFix":"// before: server returns {\"kind\":\"delete\",\"uri\":\"file:///a.py\"}\n// after: upgrade Serena so 'delete' kind is handled, or configure server to exclude resource operations","handlingStrategy":"try-catch","validationCode":"def is_supported_change(change):\n    if \"kind\" in change:\n        return change[\"kind\"] in (\"rename\",)  # extend as Serena adds support\n    return \"edits\" in change or \"textDocument\" in change\n\nif not all(is_supported_change(c) for we in edits for c in we.changes):\n    report_to_serena(we)","typeGuard":"def is_resource_operation(change) -> bool:\n    return isinstance(change, dict) and \"kind\" in change","tryCatchPattern":"try:\n    editor.rename_symbol(name_path, rel_path, new_name)\nexcept ValueError as e:\n    if \"Unhandled document change\" in str(e):\n        logger.warning(\"Language server emitted unsupported edit: %s\", e)\n        # fall back to manual edit application\n    else:\n        raise","preventionTips":["Keep Serena and language servers updated together","Test rename on a scratch file after switching language servers","Capture the full WorkspaceEdit in logs before applying to ease bug reports","Prefer servers with plain TextDocumentEdit rename results"],"tags":["lsp","workspace-edit","unsupported-operation"],"backgroundTag":"unsupported-workspace-edit-kind","analyzedSha":"7fcbca7e62555ec2287ddb2f083caee805848ea6","analyzedAt":"2026-08-29T00:04:09.619Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}