Fix Jupyter Notebook Rendering Error: 'state' key missing from 'metadata.widgets'

How to Fix It

Solution 1: Manually remove the widgets key from the notebook JSON (Most reliable)

This is the most direct fix, confirmed by multiple community members in the GitHub issue discussion. You edit the raw .ipynb file to remove the problematic key.

Steps:

1. Open your notebook in a text editor (VS Code, Notepad++, or any plain text editor). Do not open it in Jupyter for this step.
2. Search for "widgets" in the file. You will likely find it in two places:
   • At the notebook level: "metadata": { "widgets": { ... } }
   • Possibly at individual cell levels: "metadata": { "widgets": { ... } }
3. Delete the entire "widgets" key-value pair from each location. For example, change:

   "metadata": {
     "widgets": {
       "application/vnd.jupyter.widget-state+json": {}
     },
     "kernelspec": { ... }
   }
   

   to:

   "metadata": {
     "kernelspec": { ... }
   }
   

4. Save the file and push it to GitHub again. The notebook should now render correctly.

Why this works: By removing the widgets key entirely, you eliminate the source of the error. GitHub's renderer only checks for the state key if the widgets key exists. If the key is absent, the renderer skips the check entirely.

Solution 2: Use nbviewer as an alternative renderer (Community-recommended workaround)

The accepted answer strongly recommends using nbviewer instead of GitHub's built-in renderer. nbviewer is the official Jupyter community tool for sharing static notebooks. It handles many features that GitHub's renderer does not, including interactive Plotly plots, scrolling code cells, and K3D 3D plots.

Steps:

1. Push your notebook to a public GitHub repository.
2. Copy the URL of the notebook file on GitHub (e.g., https://github.com/username/repo/blob/main/notebook.ipynb).
3. Paste that URL into nbviewer's input field at https://nbviewer.jupyter.org/.
4. nbviewer will render the notebook and give you a shareable link. Share that link instead of the GitHub page.

Why this works: nbviewer is designed specifically for rendering notebooks and is more tolerant of metadata quirks. It does not require the state key to be present. As the accepted answer notes, "The view at GitHub is nothing more than a quick-preview meant for developers. It doesn't support a lot of features of notebooks, such as interactive Plotly plots, and has faulty rendering in a number of ways."

Solution 3: Use nbsanity for better rendering (Community-reported alternative)

A newer tool called nbsanity (source code at https://github.com/hamelsmu/nbsanity) was created by Hamel Husain specifically to address GitHub's poor notebook rendering. It uses Quarto as the renderer, which provides a more consistent viewing experience across platforms, including mobile.

Steps:

1. Go to https://nbsanity.com.
2. Paste the URL of your GitHub-hosted notebook.
3. nbsanity will render it and provide a shareable link.

Why this works: nbsanity is built to handle the exact metadata issues that cause GitHub's renderer to fail. It also respects Quarto directives if your notebook contains them.

Solution 4: Wait for the transient issue to resolve (If time permits)

If you are not in a hurry, the accepted answer notes that this error is sometimes transient. The GitHub issue jupyter/notebook#3555 contains reports from users who saw the error disappear after a few hours or days without any action.

Steps:

1. Push your notebook to GitHub.
2. Wait 24-48 hours.
3. Check the rendering again. If it works, no further action is needed.

Why this works: GitHub's rendering infrastructure may have intermittent bugs that get resolved on their end. This is not a reliable fix but is worth trying if you cannot modify the notebook.

If Nothing Works

If none of the above solutions resolve the issue, consider these escalation paths:

1. File a GitHub issue: The official issue tracker for this problem is jupyter/notebook#3555. Add your experience to the thread. Include your nbformat and nbconvert versions, the exact error message, and whether you are using any libraries that might inject metadata.

2. Use a different platform: If you need to share notebooks with non-developers, the accepted answer strongly advises using nbviewer exclusively. For internal sharing, consider using Google Colab or a local Jupyter server with ngrok for temporary public access.

3. Strip all metadata programmatically: As a last resort, you can write a script to remove all metadata from your notebook before pushing. This is aggressive but effective. Example Python script:

import json

with open('notebook.ipynb', 'r') as f:
    nb = json.load(f)

# Remove notebook-level metadata
nb['metadata'] = {}

# Remove cell-level metadata
for cell in nb['cells']:
    cell['metadata'] = {}

with open('notebook_clean.ipynb', 'w') as f:
    json.dump(nb, f, indent=2)

Warning: This removes all metadata, including kernel information and language info. The notebook will still render, but you may need to re-select the kernel when opening it in Jupyter.

How to Prevent It

1. Use nbviewer for sharing from the start: The accepted answer notes that "Up until a few years ago, GitHub didn't even try rendering the notebook if it had more than a few cells of code. That was better in the long run because Jupyter users realized more quickly they needed to point nbviewer at the GitHub page to see the notebook reliably." Adopt nbviewer as your primary sharing method to avoid GitHub's rendering issues entirely.

2. Inspect notebook metadata before pushing: Before committing a notebook to GitHub, open it in a text editor and check for the widgets key. If it exists and is empty or incomplete, remove it manually.

3. Keep libraries updated: The original questioner used nbformat v5.10.4 and nbconvert v7.16.6. Check for newer versions of these libraries, as later releases may fix the automatic metadata injection issue. Run:

pip install --upgrade nbformat nbconvert

4. Avoid unnecessary cell metadata: Some libraries add metadata to individual cells. If you notice this happening, consider using a clean kernel or a fresh environment for final notebook preparation.

5. Use nbsanity as a proactive alternative: If you frequently share notebooks on GitHub, consider using nbsanity as your default viewer. It is designed to handle the exact metadata issues that cause GitHub's renderer to fail.