Troubleshooting

Troubleshooting

The catalogue is empty / boj_menu returns nothing

Almost always the missing cartridge cache. Cartridges are not bundled:

scripts/fetch-cartridges.sh
export BOJ_CARTRIDGES_PATH="$HOME/.boj/cartridges"

Without BOJ_CARTRIDGES_PATH the backend falls back to a path that no longer exists and loads zero cartridges.

Tool calls return {} or cli_missing

The Elixir backend shells out to a Zig-built CLI for FFI dispatch. Build it:

cd ffi/zig && zig build && zig build invoke

Zig build fails with "no member named 'linkLibC'" / "no member named 'Mutex'"

You are on a Zig version older than 0.16, or your code is written for 0.15. Check zig version against .tool-versions. Note that mise can silently ignore the pin — verify the version you are actually running, not the one you configured.

The backend won't boot: "schema mirror … not readable"

The catalogue validates every manifest against a pinned schema mirror. If you pointed BOJ_CARTRIDGES_PATH at a cache with no sibling schemas/ directory, the server now falls back to the repo's own mirror — make sure you are on a build that includes that fallback (post-#301).

A CI check is green but I don't believe it

Reasonable instinct. Two classes exist in this repo, both documented in DEBT.md:

• Green-by-skip — abi-drift and lsp-dap-bsp are permanently gated off (run=false) and a skipped job reports SUCCESS to a required check (C-1, C-2).
• Vacuous pass — a gate whose subject was deleted, looping over nothing. Two such gates were found and fixed; if you find another, that is a bug worth reporting, not a curiosity.

Something in the docs points at boj-server/cartridges/

It is stale — that tree was retired in #300. Please open an issue; the retirement's remaining tails are tracked in DEBT.md.