Setup stops
Every refusal prints a line that starts with tokspur:. cannot open build-manifest.json means the build record is missing or unreadable, and build-manifest.json schema 2 is required means the record is in a format this build cannot read. Run scripts/bootstrap.py for either. Source drift in native/ or Source drift in rust/ means the sources changed since the recorded build, and Profile drift means a profile file changed, so run scripts/bootstrap.py again to rebuild and record them. missing configuration field means adoption or configuration did not finish, so run adopt and configure again. Confirm the system requirements before changing the machine.
Model refused
Checksum mismatch and Unexpected size mean a file differs from the pinned profile, and adopt names the file. Incomplete adopted asset set means the adoption record lists a different number of files than the pinned profile expects. Asset changed; re-adopt means a verified file was modified, moved or replaced since adoption. Stop processes using the files before replacing them, keep the originals and investigate a mismatch before adopting changed files.
Memory pressure
The selected 96 GiB profile requires 128 GiB unified memory means the Mac has less than 128 GB. On the target Mac, watch memory pressure and swap in Activity Monitor with your usual development tools running. Stop competing inference workloads and keep conversations within the context limit. A shorter conversation reduces state memory but not the size of the model weights.
Connection refused
Requested port is occupied means something else listens on the configured port, and Other inference workers found lists the processes tokspur will not run beside. Identify each process before stopping anything.
If a short text request works but the agent fails, check its streaming and tool-call settings against the connection checks. A 401 means the key is wrong, a 404 means the path is wrong, a 400 means the prompt left no room in the context or the request used a field or value the server does not support, and a 429 means another request is already waiting. The server does not name an unsupported field, so compare the request with the API contract. A 503 means the model worker failed and the server does not restart it.
Unexpected output
Confirm the adopted model files, the output limit and the client version. Record whether the problem occurs with streaming, tools, thinking or a changed conversation prefix. Separate a complete but incorrect answer from a truncated response or an interrupted stream.
Use a minimal example without private code or conversations when preparing a report.
Shutdown stalls
Ctrl-C asks the server to stop. tokspur sends the server group a termination signal and waits up to 60 seconds, then forces the group to stop and waits up to 15 seconds more. It then gives the model worker up to 45 seconds to exit, forces it if it remains and waits up to 15 seconds more. --drain-timeouts-ms sets these waits in milliseconds, in that order. If the server group survives, tokspur prints Server process group did not exit after SIGKILL. If the worker survives, tokspur prints Owned processes have not exited and lists the process IDs. Both keep .tokspur/state/process.json as a receipt. Another tokspur operation owns this state means a previous command still holds .tokspur/state/serve.lock. Verify that the model worker has exited before loading another model, and avoid stopping unrelated processes.
Useful diagnostics
The server runs in the foreground and reports refusals and status in the terminal that started it. tokspur doctor reports whether the native worker and server are built, whether the model files are adopted and configured, whether the default port is free and which other inference workers are running, without loading a model. When sharing a report, include the build version, macOS version, hardware, client version, relevant settings and the refusal line, and remove keys, private paths, prompts, tool results and conversation text first.