oraios/serena · error · ValueError

Unhandled document change format: {change}; Please report to

Error message

Unhandled document change format: {change}; Please report to Serena developers.

What it means

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.

Source

Thrown at src/serena/code_editor.py:365

    def _workspace_edit_to_edit_operations(self, workspace_edit: ls_types.WorkspaceEdit) -> list["LanguageServerCodeEditor.EditOperation"]:
        operations: list[LanguageServerCodeEditor.EditOperation] = []

        if "changes" in workspace_edit:
            for uri, edits in workspace_edit["changes"].items():
                operations.append(self.EditOperationFileTextEdits(self, uri, edits))

        if "documentChanges" in workspace_edit:
            for change in workspace_edit["documentChanges"]:
                if "textDocument" in change and "edits" in change:
                    operations.append(self.EditOperationFileTextEdits(self, change["textDocument"]["uri"], change["edits"]))
                elif "kind" in change:
                    if change["kind"] == "rename":
                        operations.append(self.EditOperationRenameFile(self, change["oldUri"], change["newUri"]))
                    else:
                        raise ValueError(f"Unhandled document change kind: {change}; Please report to Serena developers.")
                else:
                    raise ValueError(f"Unhandled document change format: {change}; Please report to Serena developers.")

        return operations

    def _apply_workspace_edit(self, workspace_edit: ls_types.WorkspaceEdit) -> int:
        """
        Applies a WorkspaceEdit

        :param workspace_edit: the edit to apply
        :return: number of edit operations applied
        """
        operations = self._workspace_edit_to_edit_operations(workspace_edit)
        for operation in operations:
            operation.apply()
        return len(operations)

    def rename_symbol(self, name_path: str, relative_path: str, new_name: str) -> str:
        """
        Renames a symbol, file, or directory throughout the codebase.

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Report the issue to the Serena developers with the full change payload from the message
2. Check for a Serena update that adds support for the change kind your language server emits
3. Switch to a language server whose rename results only contain TextDocumentEdits
4. Wrap the operation and fall back to applying edits manually via the raw WorkspaceEdit

Example fix

// before: server returns {"kind":"delete","uri":"file:///a.py"}
// after: upgrade Serena so 'delete' kind is handled, or configure server to exclude resource operations

def is_supported_change(change):
    if "kind" in change:
        return change["kind"] in ("rename",)  # extend as Serena adds support
    return "edits" in change or "textDocument" in change

if not all(is_supported_change(c) for we in edits for c in we.changes):
    report_to_serena(we)

def is_resource_operation(change) -> bool:
    return isinstance(change, dict) and "kind" in change

try:
    editor.rename_symbol(name_path, rel_path, new_name)
except ValueError as e:
    if "Unhandled document change" in str(e):
        logger.warning("Language server emitted unsupported edit: %s", e)
        # fall back to manual edit application
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unhandled document change kind: {change}; Please report to S
• Language server for {lang_server.language_id} returned no re
• Symbol '{name_path}' does not have a valid position in file
• Renaming symbol '{name_path}' to '{new_name}' resulted in no
• Failed to initialize F# language server for {self.repository

AI-assisted analysis of oraios/serena@7fcbca7e62 (2026-08-29). Data as JSON: /api/errors/62767ac07ce48a54. Report an issue: GitHub.