nberror

Collects Jupyter cell errors together with the context a traceback leaves out — DataFrame shapes, which names are missing from the namespace, and what you ran before — into one text you can hand to an AI agent, or just read yourself.

A traceback tells you where execution stopped. It rarely tells you why: that your DataFrame has 17 columns and duration is one of them while you asked for durations, or that the cell defining the variable was never run in this kernel.

pip install nberror

%load_ext nberror

That's it. Run cells as usual. When one fails you see the normal traceback plus:

[viga logitud - küsi AI-agendilt "viga" või jooksuta: nberror]

Then, from the terminal:

nberror

What the report contains

- **Erind:** `KeyError: "['durations'] not found in axis"`
- **Lahter:** In[5], kestus 2.02s

## Lahtri kood            the whole cell, not just the failing line
## Traceback
## Muutujad, mis lahtris esinevad ja on olemas
- `df`: DataFrame kuju=(45211, 17), 17 veergu: age, job, ..., duration ...
## Nimed, mida namespace'is EI OLE
- `train_balanced`
## Mis selles sessioonis enne käivitati
| In[] | tulemus | lahtri esimene rida |
| 4    | **VIGA** KeyError ... | df = df.drop(columns=['durations']) |
| 5    | ok                    | df = df.drop(columns=['duration'])  |

The last two sections solve most notebook errors. Missing names usually name the cause directly. The history shows the path — a skipped cell, a wrong order, or a kernel restart is as common a cause as wrong code.

Report text is in Estonian; the API and CLI flags are in English.

Commands

nberror                  # last error, formatted
nberror --all            # every error in the log
nberror --history        # last 25 executed cells

nberror-nb check  nb.ipynb          # static check, does not run the notebook
nberror-nb run    nb.ipynb [--upto 14]
nberror-nb map    nb.ipynb          # cell index, line ranges, stored errors
nberror-nb line   nb.ipynb 148      # which cell is line 148 in

nberror-install          # auto-load in every kernel (optional)
nberror-install --check
nberror-install --uninstall

nberror-nb check finds undefined names and out-of-order cells in about a second, without executing anything:

[DEFINEERIMATA] lahter 14, rida 4: 'train_balanced' - ei ole kusagil defineeritud
    X_train_bal = train_balanced

Use with an AI agent

Put an AGENTS.md in your project telling the agent that "viga" means run nberror and interpret the output. AGENTS.md is read without configuration by Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf and Zed; Claude Code reads CLAUDE.md, which can be a single line: @AGENTS.md.

Without an agent, read it yourself or pipe it anywhere:

nberror | clip          # Windows
nberror | pbcopy        # macOS

There is also an inline mode that calls the claude CLI and prints the explanation straight under the cell:

import nberror; nberror.activate(inline=True)

Change MODEL, or the command in _kysi_claude, to use a different model.

Where data is kept

Only failing cells are logged, so a successful cell costs nothing. "What ran before" comes from IPython's existing history database, which is opened read-only and never written to.

The log contains your code. Add .nberror/ to .gitignore.

Python API

import nberror

nberror.activate(inline=False, quiet=False)
nberror.deactivate()
nberror.last_error()            # dict, or None
nberror.format_error(entry)     # markdown string
nberror.log_path()
nberror.inputs(session, upto_line, count)

License

MIT