JupyTools.com
Back to blog
By Khalid DanishyarAbout 2 min readjupyternbformatgitguide

Repairing a Jupyter Notebook That Will Not Open

The usual ways .ipynb JSON breaks — Git conflict markers, missing cell IDs, truncated files — and what a repair tool can recover versus what is gone for good.

Recovering a Jupyter notebook that JupyterLab refuses to open

Jupyter does not open “a document.” It opens JSON that must match nbformat. When that JSON is almost right, the UI shows a brutal validation error and students assume the week’s work is gone. Often it is not.

Work on a copy. Tool: /ipynb-repair. Then confirm in /ipynb-viewer.

The failures we see over and over

Git conflict markers. A merge left <<<<<<<, =======, >>>>>>> inside the file. The result is not valid JSON. Repair tries to strip markers and parse what remains. If both sides of the merge deleted different cells, those cells are not coming back.

Missing nbformat envelope. Someone edited the file by hand and removed nbformat, kernel metadata, or the cells array structure Jupyter expects. Repair can put standard fields back when the cells are still there.

Cell IDs. From nbformat 4.5 onward, cells need unique id values. Duplicates or missing IDs cause validation errors even when the notebook “looks fine” in a text editor.

Half-written saves. A crash or a full disk can truncate the file. If the JSON does not parse even after stripping conflict markers, the tail of the notebook is missing. No honest tool will invent those cells.

Handmade “cleanup.” Deleting outputs by hand and leaving a code cell without an outputs array also fails validation. Repair can restore empty arrays. It will not restore the plots you deleted.

A recovery order that wastes less time

  1. Duplicate the file. Name it broken.ipynb.bak.
  2. If you use Git, run git status and git log — an older commit may already be valid.
  3. Open /ipynb-repair on the copy. Read every change it reports.
  4. Open the result in the viewer. If Markdown and code look complete, try JupyterLab.
  5. If plots are gone, they were never in this copy. Look at the backup or Git history.

Repair processes the upload for that request and does not keep the notebook. It is not a time machine.

When to stop and use Git instead

If the file never parsed, stop clicking “repair” on variants of the same bytes. Check:

  • Time Machine / OneDrive / Google Drive versions
  • Email attachments of an earlier draft
  • git show HEAD:path/to/notebook.ipynb

A 2-day-old valid notebook plus an afternoon of re-running cells beats a hallucinated JSON tree.

After it opens

Strip outputs before the next public commit if the file is huge: Git hygiene. If several repaired student files must become one packet, merging for grading is the next job.

FAQ

FAQ: broken notebooks

Often not. Missing nbformat fields or cell IDs are recoverable. Try /ipynb-repair on a copy. If the file is truncated JSON, repair cannot invent the missing tail.

No. Duplicate the file first. Read the change list the repair produces before you throw the original away.

Those <<<<<<< lines are Git merge leftovers inside JSON. Repair can strip many of them. If both sides of the merge deleted different cells, you may still be missing work.