Skip to main content

​
Quick checks

Start with the check that matches your problem:
Do not delete ~/.magnitude as a general troubleshooting step. It contains downloaded models, conversations, settings, credentials, and disposable caches.

​
Logs and local data

Runtime logs are stored with each session:
When Magnitude exits an active session, it prints a resume command containing the session ID. Review the log before sharing it because it may contain paths, errors, and other project information. Clearing ~/.magnitude/cache does not delete downloaded models, but it may cause hardware profiling and model evaluation to run again. It does not restore a missing bundled model catalog. See Files and directories for the complete storage reference.
Never share auth.json or API keys. Do not upload a session’s events.jsonl; it can contain prompts, conversation history, and project information.

​
Magnitude won’t start

  1. Confirm that magnitude --version works. If the command is missing, reinstall Magnitude using the instructions in Get Started.
  2. Update or reinstall the CLI if it exits before opening.
  3. On Windows, confirm that you are running Magnitude inside WSL. Native Windows is not supported.
  4. If initial setup did not finish, run magnitude --setup.
If Magnitude still does not start, include the startup error and version when getting help.

​
Model setup and downloads

​
The model catalog is unavailable

The catalog is installed with Magnitude rather than rebuilt from the internet during setup. Restart Magnitude once. If the message remains, update or reinstall the CLI so its bundled inference files and model catalog are restored together. Deleting ~/.magnitude/cache does not restore a missing catalog.

​
A model download failed

Magnitude automatically retries temporary network and server failures. If those retries are exhausted, the download view shows the failure and a Retry action. Retrying can continue a resumable partial download instead of starting from zero. You can also cancel the download and choose another model.

​
An existing Hugging Face model is not shown

Magnitude checks one standard Hugging Face Hub cache location. Open Reference and confirm which cache path applies to your environment. The model must be a compatible GGUF package. Incomplete, invalid, and incompatible packages are not available to load. After downloading a model with external Hugging Face tools, restart Magnitude to force a fresh inventory check.

​
A downloaded model is not using memory

A model can be downloaded and selected without being loaded. This is normal after it has been stopped or remained inactive for an extended period. Open /settings → Models to check its state and choose Load model. Loading places the model and its context into memory; it does not download the files again.

​
Model loading and memory

Too large does not change when other applications close. Not enough memory available can clear when more memory becomes free. A model stopped for low memory remains selected and downloaded.

​
Magnitude is waiting or running slowly

​
What the current status means

​
Prefill takes a long time

Longer conversations require more input processing before generation begins. The displayed token counts show prefill progress, and Using cached tokens shows how much compatible prompt state was reused. Prefill is separate from the generation speed reported after work completes.

​
Generation is slower than expected

Catalog speed is an estimate at the displayed context size. Actual performance varies with prompt length, other work running on the computer, and the exact model revision. Compare the completed work summary’s tok/s with the catalog estimate. Choose Fastest to prioritize response speed or Lightweight to use fewer resources.

​
Magnitude Cloud problems

Magnitude Cloud requires an active subscription and a valid API key. You can save the key in /settings → Cloud or provide it with MAGNITUDE_API_KEY. Visit the Magnitude Cloud console to confirm the subscription and create an API key.

​
Reset and reinstall

Use the least disruptive recovery that applies to the problem:
  1. Restart Magnitude.
  2. Update Magnitude.
  3. Run magnitude --setup if Local Models or Cloud setup needs to be rerun.
  4. Clear only ~/.magnitude/cache when the problem concerns derived profiling or model-evaluation data.
  5. Reinstall the CLI if bundled inference files or the bundled model catalog are missing.
Do not remove models, sessions, config.json, or auth.json unless you intentionally want the data described in Logs and local data to be removed.

​
Get help

If the problem remains, include:
  • Magnitude version from magnitude --version
  • Operating system and version
  • Chip or GPU and total memory for local-model problems
  • Exact error message
  • Selected model and configuration, when relevant
  • Steps that reproduce the problem
  • Relevant, reviewed lines from the session’s logs.jsonl
Open a GitHub issue or ask in Discord. Before sharing diagnostics, remove API keys, credentials, private code, prompts, project contents, and sensitive paths.