Server notebook document could not be converted to ty's note

Error message

Server notebook document could not be converted to ty's notebook document format: {err}

What it means

When converting a server-side notebook document into ruff_notebook's Notebook format, `Notebook::from_raw_notebook` failed (e.g. invalid cell structure or malformed nbformat fields). The code in `to_ruff_notebook` cannot recover from this and panics with this message including the underlying conversion error. It indicates the LSP client sent a notebook document whose raw JSON does not satisfy nbformat v4 requirements.

Source

Thrown at crates/ty_server/src/document/notebook.rs:128

                        }))
                    }
                    NotebookCellKind::Custom(_) => {
                        // Ignore unsupported cell kinds. This arm should never be reached unless a
                        // client sends a value which is not mentioned/supported in the LSP.
                        None
                    }
                }
            })
            .collect();
        let raw_notebook = ruff_notebook::RawNotebook {
            cells,
            metadata: self.metadata.clone(),
            nbformat: 4,
            nbformat_minor: 5,
        };

        ruff_notebook::Notebook::from_raw_notebook(raw_notebook, false).unwrap_or_else(|err| {
            panic!(
                "Server notebook document could not be converted to ty's \
                notebook document format: {err}"
            )
        })
    }

    pub(crate) fn update(
        &mut self,
        array: lsp_types::NotebookCellArrayChange,
        updated_cells: Vec<lsp_types::NotebookCell>,
        metadata_change: Option<serde_json::Map<String, serde_json::Value>>,
        version: DocumentVersion,
    ) -> crate::Result<()> {
        self.version = version;

        let new_cells = array.cells.unwrap_or_default();
        let start = array.start as usize;

View on GitHub (pinned to 26f38c119c)

Solutions

Validate the notebook JSON on the client side (nbformat validate) before opening/sending it to ty's language server.
Check the {err} detail in the panic message to identify the offending cell or field and fix it in the .ipynb file.
Reopen or reload the notebook from disk to resync the document with the server.
If a specific client produces this, report/fix the client's notebook serialization to conform to nbformat 4.x.

Example fix

// before: hand-built notebook JSON with a cell missing its id
{"cells":[{"cell_type":"code","source":"x = 1"}],"nbformat":4}
// after: valid nbformat 4.5 notebook with required ids
{"cells":[{"cell_type":"code","id":"cell-1","metadata":{},"source":"x = 1","outputs":[],"execution_count":null}],"metadata":{},"nbformat":4,"nbformat_minor":5}

Defensive patterns

Strategy: validation

Validate before calling

// Validate the .ipynb JSON before opening it in the client:
const nb = JSON.parse(notebookJson);
if (nb.nbformat !== 4 || !Array.isArray(nb.cells)) throw new Error('unsupported nbformat');
for (const cell of nb.cells) {
  if (!['code', 'markdown', 'raw'].includes(cell.cell_type)) throw new Error('bad cell_type');
  if (nb.nbformat_minor >= 5 && !cell.id) throw new Error('missing cell id');
}

Prevention

Only open notebooks produced by real .ipynb serialization (nbformat-compliant).
Validate notebooks with nbformat before syncing them to the LSP.
Avoid hand-rolling notebook JSON in editor extensions.

When it happens

Trigger: Opening or syncing a .ipynb document in the editor when the client-provided notebook JSON is structurally invalid: missing or malformed cells/cell ids, invalid source types, or an nbformat version mismatch, causing from_raw_notebook to return Err inside NotebookDocument::to_ruff_notebook.

Common situations: Editor extensions or third-party LSP clients that construct notebook documents by hand rather than from a real .ipynb file; notebooks from older/newer nbformat versions with unsupported fields; corrupted notebook state after a failed save or plugin transformation.

Related errors

AI-assisted analysis of astral-sh/ruff@26f38c119c (2026-09-05). Data as JSON: /api/errors/745436363258c521. Report an issue: GitHub.