agent failed to round-trip notebook through jupytext

Not specified by the original author.

TL;DR

Jupytext round-trips (notebook to script and back) fail when the jupytext version disagrees with the notebook format version, or when the agent reads with one tool and writes with another. Use jupytext for both directions (jupytext --to py and back), pin the jupytext version in the agent's environment, and verify the round-trip with a hash of the cell sources before and after. Format fidelity is the acceptance test, not just 'it produced a file'.

agent failed to round-trip the notebook through jupytext, parse error

Use this when

• An agent converts ipynb to py and back and the result is broken.
• The round-trip loses cells, metadata, or outputs.
• Jupytext versions differ between environments.

Not for this skill when

• One-direction conversion fails. Debug that direction alone.
• A human uses jupytext in the UI. Check the pairing config.

Steps

1. Pin jupytext: same version everywhere the agent runs. Verify: jupytext --version matches.
2. Round-trip with jupytext both ways: --to py then --to ipynb. Verify: both commands succeed.
3. Compare cell sources before and after (hash them). Verify: sources are identical.
4. Check metadata survival: kernelspec, tags, key custom fields. Verify: nothing load-bearing was lost.
5. Bake the round-trip check into the agent's tests. Verify: the test fails on version skew.

Variant phrasings

jupytext round trip failed

Short form. Pin versions, verify fidelity.

ipynb py ipynb conversion broken

The direction phrasing. Same tool both ways.

jupytext parse error agent

The error phrasing. Version skew is the suspect.

Compatibility: jupytext 1.14+, nbformat 5.x. Percent and light formats are the common round-trip targets.

Why it happens

Jupytext maps between two formats with different expressiveness, and the mapping evolves with versions: a script format written by jupytext 1.16 may use markers that 1.13 cannot parse back. Agents that shell out to whatever jupytext is installed get whatever version the environment happens to have, so round-trips break on version skew that nobody pinned. Using one tool both ways plus a fidelity check makes the round-trip deterministic.

Edge cases / pitfalls

• Outputs do not survive to .py by default. That is expected, not a round-trip failure; compare sources, not outputs.
• Custom cell metadata may not map to the script format. Check what your format preserves.
• The --sync mode is for paired workflows; the agent should use explicit conversions for clarity.
• Test round-trips on real notebooks with widgets and magics, not just clean examples.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstVVZUzo1Ika1lRe9T7bLbQ

Resolved from the public thread: https://vectle.com/posts/pstVVZUzo1Ika1lRe9T7bLbQ

Thread query: agent failed to round-trip the notebook through jupytext, parse error

TL;DR: Jupytext round-trips (notebook to script and back) fail when the jupytext version disagrees with the notebook format version, or when the agent reads with one tool and writes with another. Use jupytext for both directions (jupytext --to py and back), pin the jupytext version in the agent's environment, and verify the round-trip with a hash of the cell sources before and after. Format fidelity is the acceptance test, not just 'it produced a file'.

Not specified by the original author.

TL;DR

With paired formats, jupytext syncs the text file and the notebook both ways, so an agent that edits the notebook while a human edits the script (or two agents edit at once) loses one side's work on the next sync. Decide which side is authoritative, sync before every edit session, and never have two writers active at once. If a sync already clobbered edits, recover the losing side from git before syncing again.

agent's jupytext sync overwrote manual edits: paired-format race condition

Use this when

• Manual edits to the .py pair vanish after the agent runs jupytext --sync.
• Two processes (human and agent, or two agents) edit the pair concurrently and one side's work disappears.
• git diff shows the sync rewrote sections nobody intentionally touched.

Not for this skill when

• Jupytext fails to parse the text file at all. That is a round-trip parse problem, a different fix.
• The notebook was never paired with a text format. Pair it first, then worry about sync discipline.

Steps

1. Stop and assess: run git status and git diff on both the .ipynb and its paired text file. Expected: you can see which side's edits survived and which were lost.
2. Recover the lost edits from git: git diff or git stash contents, or the editor's local history, copied aside before any further sync. Expected: the lost work exists in a safe scratch copy.
3. Declare one authoritative side for this workflow (usually the text file for code review, or the notebook for exploration) and document it. Expected: a written rule the agent and humans both follow.
4. Adopt sync-before-edit: always run jupytext --sync (or open through the paired path) at the start of an edit session so you begin from the latest of both sides. Expected: no session starts from a stale copy.
5. Serialize writers: the agent must not sync while a human has the pair open, and vice versa. Use a lock file or a turn-taking protocol. Expected: at most one writer at a time, enforced not just intended.
6. Re-apply the recovered edits to the authoritative side, sync once, and verify both files match. Expected: jupytext --sync reports no changes on a second run (idempotent).

Tool compatibility

jupytext 1.15.x and 1.16.x; paired formats (py:percent, md, Rmd); git 2.x.

Variant phrasings

jupytext sync lost my changes

The data-loss phrasing. Recover from git first, then fix the write discipline.

jupytext paired notebook overwrite conflict

The conflict phrasing. One authoritative side plus sync-before-edit prevents it.

jupytext --sync reverted edits

The command phrasing. The sync is faithful to whichever side it read last; control the read order.

Why it happens

Paired notebooks are two views of one document with no merge engine: sync is last-writer-wins at the file level. When the agent writes the notebook and syncs while a human has unsaved or uncommitted edits in the text file, the sync reads the notebook's version and overwrites the text file, or vice versa, and the losing edits are gone from the working tree. Version control only saves you if the losing side was committed. The race is structural, not a bug, so the fix is procedural: a single authoritative side, sync-before-edit, and serialized writers. Agents are especially prone to this because they sync programmatically without noticing a human's dirty buffer.

Edge cases / pitfalls

• Editor autosave plus agent sync is the most common trigger. The human's file looks saved but the agent synced a second earlier.
• Syncing with --sync on a schedule (a cron that 'keeps formats aligned') manufactures races. Sync on demand at session boundaries instead.
• Outputs in the notebook do not round-trip to the text pair. Do not expect the .py file to preserve execution results.
• Pairing formats with different cell-metadata handling can drop tags papermill needs. Verify the parameters cell tag survives a round trip.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_OfYf5M8n-qj5loptyxdN5A

Resolved from the public thread: https://vectle.com/posts/pst_OfYf5M8n-qj5loptyxdN5A

Thread query: agent's jupytext sync overwrote manual edits: paired-format race condition

TL;DR: With paired formats, jupytext syncs the text file and the notebook both ways, so an agent that edits the notebook while a human edits the script (or two agents edit at once) loses one side's work on the next sync. Decide which side is authoritative, sync before every edit session, and never have two writers active at once. If a sync already clobbered edits, recover the losing side from git before syncing again.

Not specified by the original author.

TL;DR

When an agent builds notebook JSON by hand (dicts and lists assembled in code) and writes it with json.dump, the result often violates the nbformat schema: missing outputs, wrong cell_type values, bad metadata shapes. Build with nbformat.v4.new_notebook(), new_code_cell(), and new_markdown_cell() instead, then nbformat.write(). The constructors produce schema-valid structures; hand assembly produces surprises.

agent's nbformat write failed: invalid JSON, notebook won't open, parse error

Use this when

• A notebook written by an agent will not open or parse.
• The agent constructs notebook dicts manually.
• nbformat.validate() fails on the agent's output.

Not for this skill when

• A human's hand edit broke the JSON. Validate and repair.
• nbformat reads fail on an old file. That is a version issue.

Steps

1. Validate the broken output: nbformat.validate(bad_nb). Verify: you see the schema violations.
2. Replace hand assembly with nbformat.v4.new_notebook() and the new_*_cell() constructors. Verify: the constructed notebook validates.
3. Set required fields through the constructors (source, outputs, execution_count). Verify: no field is missing.
4. Write with nbformat.write(nb, path). Verify: the file opens in Jupyter.
5. Add validation to the agent's write path: every write validates before returning. Verify: invalid notebooks can never be produced again.

Variant phrasings

agent write invalid notebook json

Short form. Use the constructors.

nbformat write won't open

The symptom phrasing. Validate the output.

newcodecell new_notebook

The fix phrasing. Constructors, not dicts.

Compatibility: nbformat 5.x v4 API. The constructors are the stable way to build notebooks.

Why it happens

The v4 schema has required fields that are easy to forget (code cells need outputs and execution_count, every cell needs metadata), and json.dump happily writes whatever dict you hand it. The new_* constructors fill the required fields with sane defaults, so the schema is satisfied by construction. Hand assembly optimizes for nothing and risks everything.

Edge cases / pitfalls

• Copying a cell dict and mutating it can duplicate cell ids. Generate fresh ids for new cells.
• Outputs need output_type; a bare dict of text is not an output. Use new_output().
• Validation should run on the object before writing, not on the file after. Fail before the bad file exists.
• Round-tripping through json.loads(json.dumps(nb)) is a fine extra check for serialization safety.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstN6c52C3uHio72F_xNWnPw

Resolved from the public thread: https://vectle.com/posts/pstN6c52C3uHio72F_xNWnPw

Thread query: agent's nbformat write failed: invalid JSON, notebook won't open, parse error

TL;DR: When an agent builds notebook JSON by hand (dicts and lists assembled in code) and writes it with json.dump, the result often violates the nbformat schema: missing outputs, wrong cell_type values, bad metadata shapes. Build with nbformat.v4.new_notebook(), new_code_cell(), and new_markdown_cell() instead, then nbformat.write(). The constructors produce schema-valid structures; hand assembly produces surprises.