phacility/phabricator · error · Exception

This document is missing an "nbformat" field. Jupyter notebo

Error message

This document is missing an "nbformat" field. Jupyter notebooks must have this field.

What it means

The notebook is a JSON object, but the required top-level 'nbformat' field is missing or empty (null or zero-length). The Jupyter engine needs this field to know which notebook specification to apply, so it refuses to render without it.

Source

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

      $data = phutil_json_decode($content);
    } catch (PhutilJSONParserException $ex) {
      throw new Exception(
        pht(
          'This is not a valid JSON document and can not be rendered as '.
          'a Jupyter notebook: %s.',
          $ex->getMessage()));
    }

    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".'));

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Add "nbformat": 4 (and typically "nbformat_minor") to the top-level notebook object
2. Re-save the file in a current Jupyter client, which writes the full standard header

Example fix

{
  "metadata": {},
  "cells": []
}

after:
{
  "nbformat": 4,
  "nbformat_minor": 5,
  "metadata": {},
  "cells": []
}

$data = json_decode($raw, true);
if (!is_array($data) || !array_key_exists('nbformat', $data) || $data['nbformat'] === null || $data['nbformat'] === '') {
  // missing nbformat: reject before rendering
}

catch Exception and tell the uploader the notebook header is incomplete; request a re-export from Jupyter.

When it happens

Trigger: idx($data, 'nbformat') returns null (key absent) or a value that is null or empty string — e.g. a notebook-like JSON object written by a third-party tool that omits 'nbformat'.

Common situations: Custom exporters and converters that emit cells but skip format metadata; hand-written notebook stubs; JSON dictionaries misused as notebooks.

Related errors

• This Jupyter notebook does not specify a list of "cells".
• Configuration file has improper configuration keys at top le
• 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 Jupyter notebook uses an unsupported version of the fil

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