Troubleshooting
Common failures and how to fix them.
Start with amicu doctor. Then read the diagnostic code: the category tells you where to look. See Error codes. Never weaken a policy or capacity rule to make a plan pass; change the stack.
Validate and plan
AMICU-SCHEMA-003: unknown attribute. A typo, such as contex_length. The message names the block and suggests the right key.
AMICU-REF-001. A reference points at an id that does not exist. Check the spelling of model.<id>.id.
AMICU-MEM-001. The model does not fit. Lower context_length, pick a smaller quantization, or use bigger hardware.
AMICU-POLICY-004. An api_key or token was written as a quoted string. Use secret("NAME").
AMICU-POLICY-007. The provider serves off-machine and the deployment has no api_key. Add api_key = secret("NAME").
AMICU-POLICY-002 or -003. The region or provider violates a data_class or governance_rule. See Residency.
Apply
secret 'NAME' is not set in the environment. Export the variable named in secret("NAME") in the shell that runs amicu apply.
AMICU-POLICY-008. The key is empty or contains a comma, whitespace, or non-ASCII characters. Regenerate it with openssl rand -hex 32.
state is locked by another amicu process. Another amicu apply or a provider stop command is running. Wait, or use --lock-timeout <secs>. The lock is released automatically when the process exits.
llama-server not found on PATH; install with .... Install llama.cpp (macOS: brew install llama.cpp) so llama-server is on the PATH of the shell that runs amicu apply. amicu doctor reports the same.
vllm not found on PATH; install with pip install vllm``. Install vLLM into the environment whose PATH runs amicu apply.
The local service exits during startup. Apply fails within seconds, stops the service, and prints where the log is. macOS: ~/Library/Logs/amicu/<label>.out.log and <label>.err.log. Linux: journalctl --user --unit=<label>. The usual causes are a missing GGUF at the path in the plan's launch: line, or too little memory.
Apply waits and then fails with a health timeout. Apply waits up to 15 minutes for /health. If the model never loads, apply stops the service and fails; read the log named in the error.
port N is already serving /health. Something else, such as an older service or another program, answers on that port. Stop it or change llama_cpp.port / vllm.port, then apply again. Apply may wait up to 10 seconds for the previous service of the same deployment to stop before it reports this.
The local service is gone after a reboot or logout (Linux). Linux services are transient systemd user units and do not survive a reboot or logout. Run amicu apply again. On macOS the LaunchAgent persists and starts at login.
endpoint answered an unauthenticated request ... it is open to anyone with its URL. The runtime did not enforce the key. Amicu stopped the endpoint. Make sure api_key is set and the runtime is current, then apply again.
could not verify that the endpoint rejects unauthenticated requests. The endpoint never gave a definite 401 or 403. It may still be loading. Check the logs, then re-run apply.
If the stop after a failed check also failed, the error prints the command to stop it by hand: systemctl --user stop <label> on Linux, launchctl unload ~/Library/LaunchAgents/<label>.plist on macOS, or the provider's stop command (for Modal, amicu modal stop <app>).
Apply failed partway. Deployments started before the failure are recorded in state and listed in the error. Fix the cause and apply again; apply finishes the rest. See State.
Provider-specific
Each provider page has its own troubleshooting section: This machine, Modal, and the others.