Troubleshooting

Every refusal caldrix prints, with its cause and its fix. Each quoted message is the constant part of what the binary or the installer prints; the rest of the line (a path, a value, a repo name) varies.

Install and platform

The platform is not supported

is not a supported platform; caldrix ships for Linux x86_64 and macOS on Apple silicon

Cause. The installer reads uname -s and uname -m and found neither Linux x86_64 nor Darwin arm64.

Fix. Install on one of those two platforms. The release archives are listed in install.md.

The host has no usable glibc

this host does not appear to use glibc (ldd --version gave no glibc version)

this host's glibc

Cause. On Linux the installer reads the glibc version from ldd --version. The first message means ldd reported none (musl, for example). The second means a glibc was found and it is below the floor the message names (2.38).

Fix. Use a host with glibc 2.38 or newer. The message also names the container route: the CPU image ghcr.io/caldrix-ai/caldrix:latest-cpu, which is CPU only (install.md). The AMD (ROCm) image is not published yet.

The download cannot be verified

neither sha256sum nor shasum is installed, so the download cannot be verified

the download's checksum does not match

Cause. The first: the installer checks every download and has neither sha256sum nor shasum to do it with. The second: the archive does not match its .sha256 file, so nothing was installed.

Fix. For the first, install sha256sum (coreutils) or shasum. For the second, run the installer again; if it repeats, do not install the archive (install.md).

caldrix doctor lanes

caldrix doctor prints one line per lane, and --backend auto takes the first lane that says usable (doctor.md). A line saying no carries one of these reasons. Nothing in doctor launches a kernel.

No usable lane

no usable lane (

Cause. --backend auto (the default for run and serve) tried metal, hip and cpu in turn and every one was refused. The message lists each lane's reason, one per line.

Fix. Read the reasons below; the lane closest to your hardware is the one to fix. caldrix doctor shows the full report, and --backend cpu is the lane for a machine with no supported GPU.

The Metal lane

the Metal lane exists on macOS only

this caldrix was built without the metal feature

no Metal device:

Cause. The machine is not running macOS; or the binary was built without Metal support; or the Metal device query failed (the error follows).

Fix. Use the macOS release archive on Apple silicon. On another system, use the hip or cpu lane.

The AMD (HIP) lane

the AMD lane runs on Linux only

the HIP runtime did not load:

HIP loaded and reported no device

a HIP call failed:

libhipblaslt.so* not found under

ld.lld not found beside caldrix, in INFERNO_LLD or on PATH

Cause. In order: not Linux; libamdhip64.so did not load (the loader's error follows); it loaded and found no AMD GPU; a HIP call failed (a GPU architecture other than gfx942 is reported here); no libhipblaslt.so* under $ROCM_PATH/lib (or /opt/rocm/lib when ROCM_PATH is unset); no ld.lld.

Fix. Install the ROCm runtime and hipBLASLt where the message says it looked, or set ROCM_PATH. Put ld.lld beside caldrix, on PATH, or point INFERNO_LLD at it; the release archive ships one. See doctor.md.

The CPU lane

the CPU lane is built for Linux only

this host is below x86-64-v2; the CPU lane cannot run here

no C compiler: the CPU lane links its kernels with cc at load, and cc is not on PATH

Cause. Not Linux; a processor below the x86-64-v2 instruction-set level; or no C compiler named cc on PATH, which the CPU lane needs when it loads a model.

Fix. Run on Linux x86-64 with a newer processor, and install a C compiler (gcc or clang, provided as cc). See doctor.md.

Model download and import

The model argument is not a model

: no such directory

is not a directory, an alias (

Cause. The first: the argument starts with ./, / or ~ and is not a directory. The second: it is not a directory, not an alias and not a Hugging Face repo id of the form owner/name or owner/name@revision.

Fix. Give an existing directory, an alias, or a repo id (models.md). The second message lists the aliases.

The Hub refuses or cannot find the repo

the hub refused the request; the repo does not exist, or it is

: no such repo or revision on the hub

Cause. The repo is gated or private (or does not exist), or the revision does not exist.

Fix. Check the spelling. For a gated repo, accept its terms on the Hub and set HF_TOKEN (models.md).

Offline and not in the cache

is not complete in the Hugging Face cache

Cause. CALDRIX_OFFLINE or HF_HUB_OFFLINE is set, so nothing is downloaded, and the repo at that revision is not complete in the Hugging Face cache. The refusal names whichever variable is set.

Fix. Unset that variable and run once with network access, or fill the cache another way (models.md).

The repo is missing files

inferno needs config.json, a supported tokenizer and *.safetensors

the repo has no *.safetensors; inferno reads safetensors only

Cause. The repo lacks config.json, a supported tokenizer (the models page lists the files) or any *.safetensors file. GGUF, .bin and other formats are not read.

Fix. Use a repo that publishes safetensors with a tokenizer (models.md).

The weight files are refused

names no weight file

which is not a bare file name

weight file(s) that are not present

transformers_weights names a weights file

inferno does not apply an adapter to a repo that

Cause. caldrix reads the weight files the way the transformers library does: model.safetensors alone when the repo has it, otherwise the files in model.safetensors.index.json, otherwise every *.safetensors file (models.md). The index is refused (each message starts with the index's name) when it is over 16 MiB, is not an object of file names, names no file or more than 4096, names a file that is not a plain .safetensors name (or the index itself), or names a file the repo does not have. A config.json whose transformers_weights names a file is refused, because caldrix chooses files by name only. The message about not applying an adapter means the repo's weights are byte for byte its adapter's base model's, so the repo is only an adapter.

Fix. For a broken index, use a repo whose index and files agree (a partial download looks the same; download again). For the adapter message, run the base model it names.

The repo's tokenizer files are refused

which inferno cannot reproduce exactly

which inferno does not convert

whose vocab.json and merges.txt inferno

which is not in vocab.json

inferno does not guess which the model was trained with

Cause. The repo has no tokenizer.json, and its other tokenizer files set an option or have a shape inferno cannot reproduce exactly, or are a kind inferno does not convert; the message names which. A download reads the repo has no tokenizer.json, and … and stops right after config.json, so nothing else was downloaded. A model read from disk (a local directory, the cache when offline, inferno-serve --model-dir) and the browser read the model has no tokenizer.json, and …; the browser names the repo first and refuses before the first weight file.

Fix. Use a repo of the same model that publishes tokenizer.json.

The model's config.json is refused

unsupported architectures entry

exactly one is required

attention_bias true is not implemented for this architecture

nothing else was downloaded

Cause. The import checks config.json before anything else. The architecture is not LlamaForCausalLM, MistralForCausalLM, Qwen2ForCausalLM, Qwen3ForCausalLM, Qwen3MoeForCausalLM, Qwen3_5ForCausalLM or Qwen3_5ForConditionalGeneration, or config.json declares more than one; or an attention bias is set on an architecture that has none. For a Hub model the message ends by saying nothing else was downloaded.

Fix. Use a model in one of the supported architectures. The full list of what the import refuses is in models.md.

The download did not finish

the download left an incomplete snapshot at

Cause. The files were fetched but the snapshot in the cache is still missing one.

Fix. Run the same command again. Files already in the snapshot are kept, so an interrupted download resumes at the first missing file.

caldrix run refusals

caldrix refuses the argument errors in this section itself, before any model loads, and exits with status 2 (run.md). The two entries under While run answers come later and behave differently.

The model is missing or misplaced

the model is required

the model comes first, got the flag

Cause. No model argument was given, or a flag came before it.

Fix. The model is the first argument: caldrix run <model> ... (run.md).

A flag run does not take

caldrix run serves no HTTP; use caldrix serve

--model-dir: give the model as the first argument

--backend host is inferno-serve's off-hardware stand-in for its tests;

Cause. --port, --host, --admin or --admin-port was given to run; or --model-dir; or --backend host.

Fix. Use caldrix serve for HTTP flags. Give the model as the first argument. Choose auto, hip, metal or cpu for --backend (run.md).

A bad value

--backend must be auto, hip, metal or cpu, got

--max-tokens must be a positive integer, got

needs a value

Cause. The value of --backend is not one of the four lanes; --max-tokens is not a positive integer; or a flag ended the command line without its value.

Fix. Correct the value (run.md).

An unknown command

unknown command

takes no arguments, got

Cause. The first argument is not run, serve, doctor, help or version; or doctor was given an argument.

Fix. Run caldrix help for the usage.

While run answers

These happen after the model has loaded, so they are not argument errors and do not exit with status 2.

The prompt does not fit

restart with a larger --ctx or send a shorter message

Cause. The prompt is at least as long as the compiled context (--ctx, 2048 tokens by default).

Behaviour. In a chat the message is printed to stderr and the chat continues, so the next message can be sent. With -p it ends the run with exit status 1 (run.md).

Fix. Restart with a larger --ctx, or send a shorter message. In a chat, the oldest turns are dropped first to make room for the reply.

The model has no chat template

this model has no chat template; each prompt is sent as plain text, without the conversation

Cause. This is a notice printed to stderr, not a refusal; the run continues and the exit status is unchanged: the model's tokenizer carries no chat template, so caldrix run in chat mode sends each prompt alone.

Fix. None needed. Use a model with a chat template if the conversation should carry over (run.md).

caldrix serve flag refusals

caldrix serve passes your flags to Inferno's server, which refuses these before any download starts. The flags are in serve.md.

An unknown flag

unknown flag

Cause. The server does not parse that flag.

Fix. Check the spelling against serve.md.

A backend this build cannot open

the CPU lane builds for *-unknown-linux-gnu only

the Metal backend exists only on macOS, built with

Cause. --backend cpu on a system that is not Linux, or --backend metal on a build that is not macOS with Metal.

Fix. Pick the lane caldrix doctor shows as usable.

A flag that needs another

--admin requires --admin-port

--admin-port is only meaningful with --admin

is only meaningful with --weight-budget

is only meaningful with --backend cpu

Cause. --admin and --admin-port go together. --weight-pin, --weight-ring, --weight-digest, --weight-codec, --weight-pins and --layout-dir apply only with --weight-budget. --threads and --cpu-isa apply only to the cpu lane.

Fix. Add the missing flag or drop the one that depends on it.

Flags that exclude each other

streamed weights are single-stream: --weight-budget cannot be combined with --max-batch 8

streamed weights hold one session: --weight-budget cannot be combined with --admin

batched serving on the CPU lane is C3; restart with --max-batch 1

: there is no batched Metal plan (--backend metal); use --backend hip or host

the CPU lane has no variant swap in first light

Cause. --weight-budget cannot be used with --max-batch 8 or --admin. The cpu lane serves one request at a time and has no --admin. The metal lane has no batched plan.

Fix. Drop one of the two flags, or use --max-batch 1.

A value out of range

: must be 1 or 8 (the batched plan is compiled at B = 8)

--weight-budget must be a positive byte count, optionally suffixed g or m

--weight-ring must be >= 2

must differ from --port

--max-context must be >= 1

--queue-depth must be >= 1

Cause. The value is outside what the flag takes.

Fix. Use a value from the table in serve.md.