When something goes wrong

Zero works on real files that other things can also touch — another editor, a git pull, a script, a second window. Most of what follows comes from that, and none of it loses work.

If you are reporting a problem, Settings → About has the version, build, commit and commit date to quote.

The health badge

A warning badge appears in the top bar when the project has something worth looking at, and stays hidden otherwise. Clicking it opens Settings → Project Health, which lists the two things that can go inconsistent.

Stale names

Items can refer to each other, and a reference keeps a copy of the target's name so lists can be drawn without opening every file. Rename the target outside Zero and those copies go stale — the link still works, the label is out of date.

Reconcile all rewrites every stale label in the project in one pass.

Two files, one identity

Every item carries an id. Copying an item's file outside Zero — duplicating it in a file manager, merging a branch that added the same item — can produce two files claiming the same one.

Zero keeps the first one and flags the collision rather than picking a winner quietly. You resolve it per conflict:

• Keep the original — clears the flag; the other file stays on disk, unindexed.
• Use the other one — points the project at the conflicting file instead.

"This file changed while you had it open"

If a file changed on disk after you opened it, saving stops instead of overwriting. Your edits are still in the editor; the version on disk is intact. Reload to take the new version, or copy your changes elsewhere first — the point is that nothing is destroyed while you decide.

A locked item

While a long operation is working on a file — a generation run, a batch import — that file is locked and its editing controls are disabled, with a banner saying what holds it and since when. It clears itself when the operation finishes.

A file cannot be found

An asset marked broken means the record is fine but the bytes are not where they were expected: a source folder is not mounted, a file was moved outside Zero, a path is wrong on this machine.

• If a whole folder moved, fix the source — one correction repairs everything that came through it.
• If it is one file, point that asset at its file with a path override. Use a local override when the file is only in that place on your machine.

Nothing is deleted while an asset is broken. See Files, documents and sources.

A chat will not send

Almost always a setup gap rather than a fault. Check, in order: the provider is switched on, it has a key, the key is marked active, and at least one of its models is enabled. Settings → LLM Providers names whichever one is missing. See Connect an LLM provider.

The key steps do not apply to a server of your own. A provider that declares it needs no credentials is ready without one, and nothing will ever ask you for a key for it — if something appears to, that is the bug, not the missing key.

A self-hosted server is not answering

Refresh models coming back with nothing means the server did not reply — not that it has no models. Check it is actually running and at the address configured on its Models tab.

The models Zero already knew about are left in place when a refresh fails, so a server being down does not make your existing chats point at models that suddenly do not exist.

An action button is greyed out

Buttons on an object are disabled while that object's editor has unsaved changes, and the button says so. The run reads the object as saved on disk, so it would otherwise act on values you have already changed. Save, and it re-enables.

If a run is refused with a message naming a field, that field is empty and the action binds it — fill it in rather than expecting a blank to be treated as one. See Views and actions.

A document in page view shows an error in the middle of the text

That is transclusion reporting a problem where it happened: a file that is not there, an include loop, or nesting too deep. The rest of the document renders normally. See Files, documents and sources.

A generation run failed

Failed runs keep their error message on the run card, and can be restarted in place once you have dealt with the cause — a rejected key, a service that was down, a model that refused the request. The catalog lists what Zero can ask for; whether your account can actually use a given model is between you and the service, and shows up as a failed run rather than a missing option.