Skip to main content
If your harness is available, ask the agent to inspect Magnitude and fix the problem. It can run magnitude docs onboarding for the current agent-guided workflow and use the headless CLI to inspect the service, models, and connections.
Do not delete ~/.magnitude. It contains downloaded models, settings, harness connections, and Magnitude Harness sessions.

​
Setup did not finish

Ask your agent to resume setup and follow magnitude docs onboarding again. Completed hardware profiling and model downloads are reused when possible. If the CLI does not start, check magnitude --version, then update or reinstall it. On Windows, run Magnitude inside WSL. If you were using interactive setup, you can run magnitude setup again.

​
Harness cannot use Magnitude

Ask the agent to check that the Magnitude service is running and resync the harness connection. For manual recovery:
If the harness is not connected, ask your agent to resume onboarding. For manual recovery, rerun magnitude setup or add the connection from the CLI reference. Codex and Claude Code keep using Magnitude’s local gateway while their connection is installed. If the service was stopped, start it again:
To stop using the Magnitude connection instead, remove it and restart the harness:

​
Model download failed

Magnitude retries temporary network and server failures. If retries are exhausted, retry after checking network access and disk space. Partial downloads can resume instead of starting again. A GGUF model downloaded outside Magnitude must be complete and stored in a recognized Hugging Face Hub cache. Restart Magnitude after the download finishes.

​
Model will not load

A downloaded model does not use inference memory until Magnitude loads it for a request.

​
Model was unloaded

This is normally expected. Magnitude unloads inactive models and can stop a model when the machine needs memory. The model remains downloaded and selected. The next agent request loads it again.

​
Inference is slow or queued

The first request may wait for the model to load. Long prompts also require prefill before generation begins. Concurrent requests wait when the machine has no free inference capacity. Actual generation speed varies with prompt length, concurrent work, other applications, and model revision. Ask the agent to compare the active configuration with faster recommendations if sustained generation is slower than expected.

​
Logs and recovery

On macOS, service logs are in ~/.magnitude/logs/acn-service.log. On Linux, use journalctl --user -u magnitude.service. Magnitude Harness session logs are stored with each session under ~/.magnitude/sessions. Use the least disruptive recovery:
  1. Retry the request.
  2. Restart the harness.
  3. Start or restart the Magnitude service.
  4. Ask your agent to resume onboarding, or run magnitude setup again for interactive setup.
  5. Clear only ~/.magnitude/cache when derived hardware or catalog data is the problem.
  6. Reinstall the CLI if bundled inference files are missing.
Before sharing logs, remove prompts, project contents, private paths, and credentials. Open a GitHub issue or ask in Discord.