oraios/serena · error · ValueError

Unhandled document change kind: {change}; Please report to S

Error message

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

What it means

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.

Source

Thrown at src/serena/code_editor.py:363

            new_abs_path = os.path.join(self._code_editor.project_root, self._new_relative_path)
            os.rename(old_abs_path, new_abs_path)

    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:

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Report the issue to Serena developers with the language server name/version and the operation that triggered it (the message asks for this).
2. Avoid the specific LS refactoring that emits the unsupported kind; use a plain rename or manual edits.
3. Upgrade serena — support for additional kinds may have been added.
4. Check/switch the language server version to one that only emits text edits and renames for this operation.

Example fix

// before
result = editor.apply(...)  # LS emits kind:'delete' -> ValueError
// after
# upgrade serena first
pip install -U serena-agent
# if it persists, report to https://github.com/oraios/serena with the LS name/version

try:
    editor.apply(edit_call)
except ValueError as e:
    if 'Unhandled document change kind' in str(e):
        log.error('LS emitted unsupported WorkspaceEdit kind; report to serena devs with LS name/version: %s', e)
        # fall back to manual file operations for the affected files

When it happens

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

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

Related errors

• Unhandled document change format: {change}; Please report to
• Failed to initialize F# language server for {self.repository
• Invalid Content-Length header: {value!r}
• No symbols found in target file {target_file}
• FindSymbolTool returned no results

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