phacility/phabricator · error · Exception

This Jupyter notebook uses an unsupported version of the fil

Error message

This Jupyter notebook uses an unsupported version of the file format (found version %s, expected version 4).

What it means

The notebook declares an 'nbformat' value other than 4. The engine supports only nbformat 4 and enforces it with a strict comparison ($nbformat !== 4), so any other major version — and even the string "4" instead of the number 4 — is rejected.

Source

Thrown at src/applications/files/document/PhabricatorJupyterDocumentEngine.php:334

    }

    if (!is_array($data)) {
      throw new Exception(
        pht(
          'This document does not encode a valid JSON object and can not '.
          'be rendered as a Jupyter notebook.'));
    }

    $nbformat = idx($data, 'nbformat');
    if ($nbformat == null || !strlen($nbformat)) {
      throw new Exception(
        pht(
          'This document is missing an "nbformat" field. Jupyter notebooks '.
          'must have this field.'));
    }

    if ($nbformat !== 4) {
      throw new Exception(
        pht(
          'This Jupyter notebook uses an unsupported version of the file '.
          'format (found version %s, expected version 4).',
          $nbformat));
    }

    $cells = idx($data, 'cells');
    if (!is_array($cells)) {
      throw new Exception(
        pht(
          'This Jupyter notebook does not specify a list of "cells".'));
    }

    if (!$cells) {
      throw new Exception(
        pht(
          'This Jupyter notebook does not specify any notebook cells.'));
    }

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Upgrade the notebook to format 4: jupyter nbconvert --to notebook --nbformat 4 --output upgraded.ipynb old.ipynb (or open and re-save in a current Jupyter)
2. If the value is the string "4", rewrite it as the JSON number 4
3. Keep the legacy copy elsewhere and upload the converted v4 file

Example fix

"nbformat": 3,
"nbformat_minor": 0

after:
"nbformat": 4,
"nbformat_minor": 5

$nbformat = idx($data, 'nbformat');
if ($nbformat !== 4) {
  // strict check: string "4" also fails; convert or reject
}

catch Exception and direct the user to convert the notebook to format 4 (jupyter nbconvert --nbformat 4).

When it happens

Trigger: nbformat 3 (legacy IPython-era notebooks) or any newer/experimental format; also 'nbformat': "4" written as a JSON string, which fails the strict !== comparison against integer 4.

Common situations: Old v3 notebooks from the IPython era kept in archives; tools that serialize nbformat as a string; internal formats bumping the major version.

Related errors

• This is not a valid JSON document and can not be rendered as
• This document does not encode a valid JSON object and can no
• This document is missing an "nbformat" field. Jupyter notebo
• This Jupyter notebook does not specify a list of "cells".
• This Jupyter notebook does not specify any notebook cells.

AI-assisted analysis of phacility/phabricator@5720a38cfe (2026-08-21). Data as JSON: /api/errors/f07af8a100cd850b. Report an issue: GitHub.