When it refuses

DunneFlow is designed to be deterministic: run it twice on the same tree and you get the same map. Where it cannot give a trustworthy answer, it refuses rather than guesses, and every refusal names something you can act on. A fallback that produces a plausible value hides the failure it was written for, and a map that looks right and is wrong is worse than no map.

Written by a different version#

error: output/some-project/graph@2026-09-09T15-32-15Z.db was written by a different
version of DunneFlow and cannot be read safely -- re-run `dunneflow analyze` to rebuild it

What happened. DunneFlow was updated. A map records which extractor and detector rules produced it, and a newer build will not read an older store as if it were its own.

What to do. Analyse the tree again. Unchanged files are cached, so it is quick.

If it names standards.db, re-run with --standards pointing at the same standards directory. A rebuild that omits --standards analyses perfectly and then refuses to open. If you no longer have the standards directory, delete standards.db.

If you have sealed snapshots, they are stale too; rebuild them oldest first as in Comparing two versions.

Facts from a different reader#

error: output/some-project/graph@….db holds facts from a reader this build is not:
typescript (read by 1.1.0:92eb0d173e9807a7). Re-run `dunneflow analyze` -- it re-reads
only the language that changed, and leaves the rest of the map alone.

What happened. The reader for one language changed while the rest of the tool did not. DunneFlow records per file which reader produced its facts.

What to do. Analyse again. Only the named language is re-read.

Node.js is missing#

typescript needs `node` ≥ 20.0.0 and nothing answers `node --version` on this machine.
Install it (brew install node, or nodejs.org), or run again with `--without typescript`
and the map will say those files were declined.

What happened. The tree contains TypeScript, which DunneFlow reads with TypeScript's own compiler, and that needs Node.js 20 or newer. The check happens before anything is read.

What to do. Install Node.js, or analyse with --without typescript. The run prints what you declined, and About this map records it. Declining every language the build reads is refused, since that would be a map with no code in it. If the tree holds no TypeScript, Node is never asked for.

Stores absolute paths#

error: output/some-project/graph@….db stores absolute paths, from before DunneFlow made
them relative to the tree they were read from -- run `dunneflow migrate output/some-project`
to rewrite it in place

What to do. Run the command it names:

uv run dunneflow migrate output/some-project

It rewrites stored paths in place rather than re-analysing, so sealed snapshots whose source is gone survive. A reader never repairs a store silently on the way past.

Never finished#

error: some-project was never finished: an analysis stopped while reading the documents.
What it holds is part of a program, not a program. Analysing it again completes it — the
extraction is cached, so it takes seconds rather than the whole run.

What happened. An analysis was interrupted: you pressed Stop it, the machine slept, or the process was killed. A half-written graph opens perfectly and is wrong.

What to do. Analyse it again; it picks up where it stopped. One command proceeds anyway and warns: dunneflow query, whose contract is to return the rows that are there.

Is the program being read#

dunneflow is the program being read — its graph is open here, and an analysis may
discard and re-extract it. Switch to another program first, or run this from a terminal.

What happened. You asked the dashboard to analyse into the name it is currently serving, which could empty the map while you read it.

What to do. Switch the program menu to something else first, or run dunneflow analyze from a terminal against a server that is not serving that program.

Maps disk not there#

maps are kept in …/DunneFlow, which is not there right now —
reconnect that disk, or choose somewhere else

What happened. You moved your maps to another disk and it is not connected.

What to do. Reconnect it, or press Choose somewhere else on the start page. DunneFlow falls back to the standard location so the application still opens, and says so in the terminal and in a banner. It will not create the missing directory: on every platform that would risk creating an empty maps folder on your startup disk, or on the wrong drive.

No folder picker (Linux)#

no folder picker is installed — zenity or kdialog would give you one;
type the whole path instead

What to do. Type the path into the field, or install zenity or kdialog.

No desktop session (Linux)#

there is no desktop session here to open a window in — type the whole path instead

What happened. DunneFlow is running without a display, for example over SSH, and you asked for a window. Show me refuses for the same reason.

What to do. Type the path.

Tree too large to read in one go#

If a tree has more files than DunneFlow is known to read in a single run, analyze refuses and prints the tree cut into parts that are each within that size, with the command to analyse each one into the same maps root. --parts prints that breakdown without analysing; --any-size overrules the refusal.

Refusals from the Analyse dialog#

And one note rather than a refusal: analysing into an existing program rewrites its working snapshot; seal it first if you want to keep both.

Refusals about a standards directory#

--standards admits somebody else's naming rules. It is refused if the directory is inside the output root, inside the documentation root (it is already read), or inside the analysed tree (then it is the program's own documentation, not an outside standard). Keep standards somewhere permanent, outside both.

A 409 from a freshly started server#

If a request arrives before any map is open, the server answers 409 with a sentence saying so. You normally see this only from a bookmarked dashboard URL. Go to /start and open a program.

When the map looks wrong, not broken#

• A large program with almost no internal calls usually means a partial checkout. What is not on disk is not in the map. See Getting the code.
• An entry point that reaches almost nothing when you know it does more usually means a framework registers handlers in a way DunneFlow's detectors do not yet recognise. Teaching it one is normally a configuration edit in detectors/*.yaml rather than a code change.
• A finding that is really a limitation of DunneFlow. Press 3 on it in the worklist to triage it as a defect in the tool.