Install
command not found: kolm
The npm global bin is not on your PATH. Run npm config get prefix and add $(prefix)/bin to your shell profile, or reinstall with npm install -g @kolmogorov/kolm after fixing the prefix.
EACCES on npm install -g
Avoid sudo. Set a user-owned prefix: npm config set prefix ~/.npm-global, then add ~/.npm-global/bin to PATH. Reinstall.
Node version too old
kolm requires Node 20+. Check with node -v. Upgrade via your version manager (nvm, fnm, volta).
Auth & API key
401 unauthorized on kolm compile
Your key is missing or wrong. kolm login writes the key to ~/.kolm/config.json. To inspect: cat ~/.kolm/config.json. To rotate: kolm logout && kolm login.
402 payment required
The free tier ran out of compile minutes for the month or your plan was downgraded. Check /account. Upgrade at /pricing or wait for the next reset.
429 rate limited on signup
Signup is gated to 10 attempts per IP per 24 hours. If you are testing from a shared egress, switch IPs or wait. This is not a bug.
Compile
K-score below gate, artifact not produced
The compile log names the failing sub-score (accuracy, size, latency, cost, coverage). Most common: accuracy below threshold because the example set is too small or contradictory. Add more examples; remove contradictions; rerun. To ship a prototype anyway, override with --gate 0.70 (not for production).
verifier synthesis failed
Your task description does not name a verifiable property. Either (1) add 5 to 10 paired examples that the verifier can learn from, or (2) tighten the task to one judgable output (classification, extraction, structured output). Free-form generation tasks need a regex/JSON-schema check or a paired-LM judge.
teacher API returned 4xx
Your frontier key is invalid or out of quota. kolm uses your own Anthropic / OpenAI / Google key for k-sample inference and stops if the provider rejects. Check the key against https://api.anthropic.com/v1/messages directly, then re-run.
compile job stuck at "k-sampling"
Frontier provider is slow or rate-limiting. The job will resume; do not cancel. If it has been over 30 minutes, kill the job (kolm compile --cancel <job-id>) and retry with --k 4 instead of the default 8.
distill ran out of memory
Your base model is too large for the build host. On Free tier, only Phi-3-mini and Qwen2.5-3B fit. Pro and above support up to 14B. Upgrade or pick a smaller base.
artifact size exceeds budget
The compile log shows the budget and the actual. Drop the base to a smaller model, prune the recipe pack with --max-recipes, or accept the size penalty by raising --budget-mb.
Run
kolm run: signature does not verify
The artifact was tampered with after compile, or the file is partially downloaded. Re-fetch from the original source. kolm inspect <file> shows the manifest hash; compare it to the publisher's hash. Never run an artifact whose signature does not match.
kolm run: model file missing
The artifact zip is corrupt or truncated. unzip -l <file.kolm> should list seven entries. Re-download.
kolm run: tokens/sec below my expectation
Check that you are running the matching runtime for your hardware. kolm run --device auto picks Metal on Apple silicon, CUDA on NVIDIA, CPU otherwise. Force with --device metal or --device cuda.
kolm run: prompt exceeds context window
The base model has a fixed window. Either trim input, switch to a base with longer context (--base at compile time), or use the recipe-mode shortcut which routes long prompts through recall.
Verify
kolm verify: receipt chain broken
One of the four HMAC rings does not match. The artifact has been modified since signing, or the runtime mis-recorded the receipt. Open kolm verify --explain to see which ring failed; ring 1 (model) failure means a tampered weights file, ring 4 (manifest) failure means metadata edits.
kolm verify: signature key not recognized
The artifact was signed by a key not in your trust store. kolm trust add <key-id> after confirming the publisher. For self-published artifacts, the key is in ~/.kolm/config.json.
Serve
kolm serve --mcp: client cannot find the server
MCP discovery uses mDNS plus a .well-known/mcp.json on loopback. Confirm the server is on with kolm serve --status and that the client (claude code, cursor, continue) is configured for stdio or SSE. Loopback first; only expose externally if you understand the auth implications.
kolm serve: port in use
Default is 7327. Change with --port 7328. To find what is on 7327: lsof -iTCP:7327 -sTCP:LISTEN.
MCP tool calls return empty
The artifact has no exposed tools, or the recipe pack is empty. kolm inspect <file> shows the recipe count. Compile with --export-tools if your task involves callable functions.