Troubleshooting
The failures people actually hit, what each one means, and the command that tells you which it is.
Start with axiom caps --game <id>. It answers most of this page in one screen.
A mod will not load
| What you see | Means | Fix |
|---|---|---|
absent beside a required cap | No pack answers it on this game | Install a pack that provides it, or make it optional and degrade |
disabled by pack | Provided but turned off | Enable it in the game's pack settings |
| Capability not recognised | Typo, or a retired major | axiom check names the replacement |
Mod wants @2, pack gives @1 | Version mismatch | Update the pack, or use a build against @1 |
Everything returns Failed{ SymbolUnresolved }
The game patched. axiom symbols --game <id> shows which names failed on this build. Either the pack
has a newer version covering it, or nobody has published one yet.
Attach refuses to guess an address rather than resolving to a plausible wrong one. A framework that guessed here would read the wrong bytes silently, which is the failure mode this whole architecture exists to avoid.
Entity data is nonsense, but nothing errors
A conformance failure, almost always. Check axiom caps for the score and axiom pack test for which
test fails.
| Failing test | What it means |
|---|---|
count_matches_enumeration | The pack is misreading the free list |
position_is_metres | The pack is not converting units, every mod on it is wrong |
rotation_is_radians | The pack is handing through the game's degrees |
bulk_matches_scalar | Two code paths in the pack disagree |
My keys stopped working in game
A mod is holding input capture. Open the overlay and run capture, which names the holder. Escape
always releases the overlay's own capture. A mod that takes capture and never releases it is a mod
bug, not a configuration problem.
The game stutters since installing a mod
Overlay, Performance tab. It breaks the frame down by mod with crossings counted. A Tier W mod over a few hundred crossings a frame is calling something scalar in a loop.
| Pattern | Crossings per frame |
|---|---|
transform(id) and world_to_screen(p) per entity, 400 entities | 801 |
transforms(ids) and world_to_screen_many(ps) | 4 |
A Tier N mod crashed the game
That is the tier working as designed: native mods have no sandbox and a fault is fatal. The manager records the crash against the mod with the fault address. Nothing can be done from Axiom's side except not loading it, which is the main argument for Tier W.
A pack exists but my build is not covered
axiom pack list --game <id> shows every pack with the builds it covers, and another pack may already
cover yours. Packs stack, so a second pack can answer only the questions the first one misses. Failing
that, a pack can be forked and extended with one [[build]] block and a symbols file, by anyone, with
no permission needed.
The game shows as Blocked
Kernel anticheat. This is not a bug or a configuration problem, and there is no flag for it.
Nothing in Axiom will attach to that process. The check runs in the manager, in the registry and at attach, regardless of what a pack claims.