Fix Jupyter Notebook 'state' key missing from metadata.widgets error

The 'state' key missing from 'metadata.widgets' error in Jupyter notebooks occurs when GitHub's quick-preview renderer encounters malformed or incomplete widget metadata, even if you never used ipywidgets. The fix is to either remove the metadata.widgets section entirely using a script, use nbviewer for reliable rendering, or switch to nbsanity for a modern mobile-friendly viewer. This guide covers all solutions from the community and official discussions.

The Full Answer

This error has been reported in multiple GitHub issues (notably jupyter/notebook#3555) and Stack Overflow threads. The root cause is that GitHub's built-in notebook renderer (a quick-preview mode meant for developers) is strict about the structure of the metadata.widgets field. Even if you never added widgets, some Jupyter versions or extensions (like those used with Hugging Face LLM notebooks) may insert an empty or incomplete metadata.widgets dictionary. The error message reads:

There was an error rendering your Notebook: the 'state' key is missing from 'metadata.widgets'. Add 'state' to each, or remove 'metadata.widgets'.

According to the official Jupyter discussion in issue #3555, this is a known intermittent issue. Some users report that the problem resolves itself over time, possibly due to GitHub's caching or rendering pipeline changes. However, relying on time is not a reliable fix. The community has developed several workarounds, each with different trade-offs.

Solution 1: Remove metadata.widgets with a script (permanent fix)

This is the most direct fix. You can strip the problematic metadata from your notebook file using Python or a command-line tool. The goal is to delete the entire metadata.widgets key from the notebook's JSON structure.

Prerequisites: Python 3.x with the nbformat library installed (it comes with Jupyter).

Step 1: Create a Python script named clean_notebook.py with the following content:

import nbformat
import sys

if len(sys.argv) != 2:
    print("Usage: python clean_notebook.py <notebook.ipynb>")
    sys.exit(1)

notebook_path = sys.argv[1]

with open(notebook_path, 'r', encoding='utf-8') as f:
    nb = nbformat.read(f, as_version=4)

# Remove metadata.widgets if it exists
if 'widgets' in nb.metadata:
    del nb.metadata['widgets']
    print("Removed metadata.widgets")
else:
    print("No metadata.widgets found")

# Also clean per-cell widget metadata if present
for cell in nb.cells:
    if 'metadata' in cell and 'widgets' in cell.metadata:
        del cell.metadata['widgets']

with open(notebook_path, 'w', encoding='utf-8') as f:
    nbformat.write(nb, f)

print("Notebook cleaned successfully")

Step 2: Run the script on your notebook:

python clean_notebook.py your_notebook.ipynb

Step 3: Commit and push the cleaned notebook to GitHub. The error should no longer appear.

When to use this: If you need the notebook to render correctly on GitHub's built-in viewer and you don't rely on any widget functionality. This is the most permanent fix because it removes the problematic metadata entirely.

Caveat: If you later add widgets to the notebook, you will need to re-add the metadata.widgets section manually or let Jupyter regenerate it. The script does not preserve any widget state, so only use it on notebooks that truly have no widgets.

Solution 2: Use nbviewer for reliable rendering (recommended for sharing)

nbviewer is the official Jupyter community tool for rendering notebooks as static web pages. It is designed for sharing notebooks with non-developers and supports many interactive features that GitHub's viewer does not, such as:

• Interactive Plotly plots (compare this GitHub gist to its nbviewer rendering).
• Horizontal scrolling for long code cells (GitHub's viewer truncates or wraps code).
• Animations with frame controllers (e.g., K3D 3D plots, nilearn visualizations).

To use nbviewer:

1. Push your notebook to a public GitHub repository.
2. Go to nbviewer.jupyter.org.
3. Enter the URL of your notebook on GitHub.
4. nbviewer will render the notebook and give you a shareable link.

When to use this: If you are sharing notebooks with colleagues, students, or the public. nbviewer's rendering is more robust and feature-rich than GitHub's. It also avoids the 'state' key error entirely because nbviewer uses a different rendering engine that is more forgiving of metadata issues.

Caveat: nbviewer only works with public notebooks. For private repositories, you will need to use one of the other solutions.

Solution 3: Use nbsanity for modern mobile-friendly rendering

nbsanity.com is a newer alternative created by Hamel Husain (source code at github.com/hamelsmu/nbsanity). It uses Quarto as the renderer, which provides a more sane viewing experience across devices, especially mobile. Key features:

• Horizontal scrolling works on mobile (nbviewer does not support this).
• Respects Quarto directives if your notebook uses them.
• Lightweight and fast.

To use nbsanity:

1. Push your notebook to a public GitHub repository.
2. Go to nbsanity.com.
3. Enter the URL of your notebook.
4. nbsanity will render it and provide a shareable link.

When to use this: If you need mobile-friendly rendering or want to use Quarto features. As of December 2024, Hamel Husain announced ongoing improvements to nbsanity, making it a strong choice for technical content creators who use notebooks as a microblogging medium.

Caveat: nbsanity is a third-party service, not officially affiliated with Jupyter. It requires a public notebook URL.

Solution 4: Wait for GitHub to fix the transient issue

According to the GitHub issue discussion (jupyter/notebook#3555), this error sometimes resolves itself after a few hours or days. This suggests a caching or rendering pipeline issue on GitHub's side. However, this is not a reliable fix and should only be considered if you are in a hurry and the other solutions are not feasible.

When to use this: If you have already tried the other solutions and the error persists, or if you cannot modify the notebook (e.g., it belongs to someone else).