Skip to main content
llmwiki tracks each project’s compilation state in .llmwiki/state.json. That file carries a schema version, and each llmwiki build understands schema versions only up to the one it shipped with. If you run an llmwiki build against a project whose .llmwiki/state.json was written by a newer llmwiki version - for example, a teammate compiled with a newer release, or a stray newer binary touched the project - the state file declares a schema version this build does not recognize.

​
What “written by a newer llmwiki version” means

It means .llmwiki/state.json has a version field higher than the highest version your installed llmwiki understands. The newer build may have written fields or a layout your build cannot safely interpret. When this happens, llmwiki fails closed. Rather than risk misreading the file - or overwriting a forward-incompatible layout on the next compile and corrupting it - commands that read state stop with a clear error instead of proceeding:
This is deliberate. The safest action when llmwiki encounters state it doesn’t understand is to refuse to touch it.

​
Two ways forward

​
Upgrade llmwiki

If you want to keep the existing compilation state - the recorded source hashes and the incremental-compile tracking - upgrade your llmwiki install to a version at least as new as the one that wrote the file. The newer build understands the schema and reads the project as-is.

​
Reset the state file

If you are pinned to an older llmwiki and cannot upgrade, or you simply want to move forward from a clean slate, reset the state file with llmwiki state reset. This backs up .llmwiki/state.json to .llmwiki/state.json.bak and removes it, so the next llmwiki compile rebuilds state from your current sources/.

​
llmwiki state reset

state reset refuses by default. Run it with no flags to see exactly what it will do without changing anything:
When you’re ready, pass --yes to apply the reset:
The backup is a single atomic rename: the original bytes are preserved at .llmwiki/state.json.bak (overwriting any earlier backup), and the original file is removed.
state reset --yes operates on the raw file bytes and never parses or validates the state. That’s what makes it a reliable recovery path: it works even when the state file is too-new or otherwise unreadable - the very situation that would otherwise block you.
If there is no state file to reset, the command says so and makes no changes:

​
After resetting

Run a full compile to rebuild state from the current sources:
This regenerates .llmwiki/state.json at your build’s schema version and produces fresh pages. Incremental compilation and source freshness tracking resume normally from there.
The backup at .llmwiki/state.json.bak is left in place. If you later upgrade llmwiki and want the original newer-version state back, you can restore it by renaming the backup to .llmwiki/state.json - then the upgraded build can read it directly.