Ruff crashes when marimo notebook and text editor views are open simultaneously

[manzt]

We're preparing to ship the marimo VS Code extension and have identified a compatibility issue with Ruff.

Marimo notebooks use .py files and register as a custom notebook type via VS Code's notebook API. When the same file is open in both notebook view and text editor view, Ruff crashes with errors like:

ERROR An error occurred while running notebookDocument/didChange: Notebook document URI does not point to a notebook document
ERROR An error occurred while running notebookDocument/didChange: Document controller not available at `file:///path/to/notebook.py`

It appears Ruff's document tracking seems to get confused when it receives notifications about the same .py file existing as both vscode-notebook-cell:// URIs and regular file:// URIs. I'm guessing this works fine with Jupyter because it uses .ipynb files, but breaks with marimo where the notebook format is .py.

Reference:

• Ruff Language Server marimo-team/marimo-lsp#178

Environment: Ruff extension 2025.28.0, VS Code 1.105.1, ruff.nativeServer: true

[MichaReiser]

Can you share the ls messages that the extension sends (I'm mainly interested in didOpen and didChange for normal documets and notebooks)

[MichaReiser]

I installed the marimo extension, opened a file as marimo notebook, and then opened it as normal text document.

The important bits from the logs are:

Opening main.py as a notebook

Trace - 9:45:41 AM] Sending notification 'textDocument/didClose'.
Params: {
    "textDocument": {
        "uri": "file:///Users/micha/astral/test/main.py"
    }
}


[Trace - 9:45:41 AM] Received notification 'textDocument/publishDiagnostics'.
Params: {
    "diagnostics": [],
    "uri": "file:///Users/micha/astral/test/main.py",
    "version": 1
}


[Trace - 9:45:53 AM] Sending notification 'notebookDocument/didOpen'.
Params: {
    "notebookDocument": {
        "uri": "file:///Users/micha/astral/test/main.py",
        "notebookType": "marimo-notebook",
        "version": 1,
        "cells": [
            {
                "kind": 2,
                "document": "vscode-notebook-cell:/Users/micha/astral/test/main.py#W0sZmlsZQ%3D%3D"
            }
        ],
        "metadata": {
            "app": {
                "options": {}
            },
            "header": {
                "value": "class Base: \n    b: int\n\nclass Test(Base): \n    a: str"
            },
            "version": null,
            "violations": [
                {
                    "description": "Only able to extract header.",
                    "lineno": 1,
                    "col_offset": 0
                },
                {
                    "description": "non-marimo Python content beyond header",
                    "lineno": 1,
                    "col_offset": 0
                }
            ],
            "valid": false
        }
    },
    "cellTextDocuments": [
        {
            "uri": "vscode-notebook-cell:/Users/micha/astral/test/main.py#W0sZmlsZQ%3D%3D",
            "languageId": "python",
            "version": 1,
            "text": ""
        }
    ]
}

It first closes the text document and then opens it as a notebook file. This looks correct

Opening main.py from the side panel

[Trace - 9:46:08 AM] Sending notification 'textDocument/didOpen'.
Params: {
    "textDocument": {
        "uri": "file:///Users/micha/astral/test/main.py",
        "languageId": "python",
        "version": 1,
        "text": "class Base: \n    b: int\n\nclass Test(Base): \n    a: str"
    }
}

The same file with the same URI is opened again.

I don't see how RUff can support this. The URI must be unique because it's the only identifier Ruff can use to refer to a document, and offsets have different meanings depending on whether the document is a regular text file or a notebook.

I think we should exclude marimo documents when registering notebook capabilities, since Ruff doesn't support them (https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#notebookDocumentFilter). Or more specifically, we should only register for jupyter notebooks because that's the only notebook type that Ruff/ty support.

I still think it's problematic for the marimo extension to use the same URI for the same file (or to allow opening the text document alongside the notebook). Even if Ruff wanted to support marimo notebooks, I don't see how, given that it's no longer possible to uniquely identify a document.

[MichaReiser]

I think we should exclude marimo documents when registering notebook capabilities, since Ruff doesn't support them (microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification#notebookDocumentFilter). Or more specifically, we should only register for jupyter notebooks because that's the only notebook type that Ruff/ty support.

I was just about to make this change when I realized that this is a bad idea. Ruff can handle any notebook that's supported by VS Code just fine. It would mean we remove marimo notebook support for no good reason (disabling Ruff/ty support across all marimo notebooks).

I think this is an issue you have to solve upstream in your extension rather than asking each LSP server to special-case marimo notebooks.

[mscolnick]

@MichaReiser can you explain how the URIs are the same? The notebookUri matches the plain textDocument URI, but the cell's textDocument URI is vscode-notebook-cell:/Users/micha/astral/test/main.py#W0sZmlsZQ%3D%3D. Why would that URI not be used instead?

[MichaReiser]

can you explain how the URIs are the same? The notebookUri matches the plain textDocument URI,

This is the issue. LSPs internally keep a map from URL to document, where the URL is a unique identifier. That makes it impossible to have both a text document and a notebook document for the same URL.

The way the LSP models documents is:

• regular files: A single text document
• notebooks:
  • a notebook document
  • for each cell, a text document

Each of those documents are identified by a unique URL. Now, what happens when the same file is opened as both a text document and as marimo notebook is that:

1. There's one text document for the "regular" file
2. There's one notebook document for the marimo notebook
3. There's a text document for each cell in the notebook

The issue is that 1. and 2. use the same URL, which is supposed to be unique.

[mscolnick]

Got it, so VersionedTextDocumentIdentifier and VersionedNotebookDocumentIdentifier (according to the LSP spec) are being treated the same in ruff. Those feel different and just because they have the same URI does not make them the same (to me). But I understand this this likely simplifies implementation consolidating NotebookDocuments and TextDocuments under just "Documents". Fwiw, this does not seem to be an issue with other LSPs.

[MichaReiser]

Fwiw, this does not seem to be an issue with other LSPs.

Do these other LSPs support notebook synchronisation?

Those feel different and just because they have the same URI does not make them the same (to me)

I can see where you coming from and, indeed, it doesn't make much of a difference for didChange and didOpen where you always know what the type of the document is.

However, it becomes ambiguous for semanticTokens where all the server has is the URI. I believe VS Code never sends that request for an entire notebook, so we could maybe assume that it is a text document but that's something I rather avoid as it isn't specified in the LSP specification.

The part where it becomes really tricky, indeed, impossible for the LSP to know what it should do if the URI isn't unique, is when it needs to map an internal location to an LSP location. Let's say there's a multi-file diagnostic and it has related information in a file that's both open as a notebook AND as a text file. Which location should the LSP use? The line/column information of the text document or of the cell, or both? All these have suboptimal results:

• Only text document: The related diagnostic doesn't appear in the notebook
• Only the cell: The related diagnostic doesn't appear in the text document
• Both: The related diagnostic appears twice in the diagnostic panel

What's the reason for allowing a document to be open both as a normal document and as a notebook at the same time? Ensuring that a document is always only open as regular OR notebook at any given time would fix the ambiguity and also matches my expectation as a user.

[manzt]

What's the reason for allowing a document to be open both as a normal document and as a notebook at the same time? Ensuring that a document is always only open as regular OR notebook at any given time would fix the ambiguity and also matches my expectation as a user.

I agree that would be the ideal starting point. Sadly, this isn't something we can enforce. The sequence you saw at the beginning—where the text document closes and then a notebook opens—is something we control only via a custom button (the marimo icon) in the toolbar.

However, users can also use VS Code's native "Open With..." menu (below) to open the same file with multiple editors simultaneously (text editor, notebook editor, custom editor). We have no way to prevent VS Code from allowing this, and it's by design that the same file can be open with different editor types at the same time.

I understand the ambiguity this creates and the preference to avoid special casing. That said, I noticed there's already some URI inspection in the codebase (specifically around .ipynb), so I'm hoping we could explore a solution together—even if it's just gracefully handling the conflict to avoid crashes. Right now it's a pretty rough experience for our users, many of whom love both marimo and Ruff.

[MichaReiser]

Yeah, this is interesting. I suspect this isn't an issue for most other LSPs because they don't support the raw-notebook format AND the notebook at the same time. E.g., opening the raw notebook and the Jupyter notebook side-by-side isn't an issue because Ruff isn't subscribed to JSON text documents. The same is true for the built-in JSON language server; it only handles text documents, but it doesn't register for notebook synchronisation.

I quickly checked Pyrefly (I know that ty has the same issue), and I suspect you'll run into similar issues where the LSP either crashes or just stops working for one of the documents because they also use the URL as a unique key for a document, which can be either a notebook or a text document.

so I'm hoping we could explore a solution together—even if it's just gracefully handling the conflict to avoid crashes. Right now it's a pretty rough experience for our users, many of whom love both marimo and Ruff.

I'm not sure what Ruff can do to reconcile this without a full refactor to support having text and notebook documents open side to side:

• Ignoring didOpen (text document) when the notebook's already open: Ruff won't work in the text document, even after the user closed the notebook.
• Disable Ruff for marimo notebooks

The cleanest seems to refactor ty and Ruff to support having both files open at the same time, but it's honestly not clear to me from the LSP spec what a server is supposed to do in that case. Does it need to publish diagnostics for both? Do we need to track for every request if it was made from a text or notebook document and use the corresponding mapping? How would we even know if it's one or the other (requests only contain the URL!), or do we need to assume that the only place where a URL points to a notebook (not a cell) is in the didNoteook* methods?

I did spend a good time going through the LSP specification in the hope of finding some clarification, but its language is, unfortunately, not very clear:

notebook document: a collection of notebook cells typically stored in a file on disk. A notebook document has a type and can be uniquely identified using a resource URI.

What does uniquely identified mean here? Is the URI globally unique or only unique across notebook documents?

Either way, this would be a larger change to both ty and ruff, and I don't see myself having time to look into this anytime soon. I'm sorry.

Is there a way you could change the language of the text document to something other than Python (for as long as the notebook is open)?

[MichaReiser]

The only thing I can offer from our side is that we ignore any didOpen requests for the normal text document while the document is open as marimo notebook. I think this would be strictly better than crashing, as it is the case today, but it's still a very suboptimal experience because linting and formatting won't work in text documents if the document is opened while also open as a notebook.