> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magnitude.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Find the problem and take the next useful action.

Start with **Status** in Desktop or `magnitude status` in a terminal. It distinguishes service startup from model loading and downloads.

## The service won't start

Read the error on Status and use **Retry service** when offered. If it reports an occupied port, close the application using that port before retrying. For a headless server, read the error printed by `magnitude serve`.

For terminal diagnostics:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
magnitude status
```

## Another Magnitude instance is running

Fully quit Desktop before starting `magnitude serve`. Closing its window can leave it running. If another `serve` command is running, stop that command before starting another.

## Magnitude command not found

Open a **new terminal** and run `magnitude --help`.

* **macOS:** open Desktop once to register the CLI in your shell. Without a graphical session, run `/Applications/Magnitude.app/Contents/Resources/magnitude` directly.
* **Windows:** the installer updates your user PATH; existing terminals may retain the old PATH. Rerun the installer if command registration failed.
* **Linux:** install the desktop package through your package manager; it owns `/usr/bin/magnitude`.

If an old CLI still runs, inspect which executable your terminal finds:

<Tabs>
  <Tab title="macOS / Linux">
    ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
    command -v magnitude
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
    where.exe magnitude
    ```
  </Tab>
</Tabs>

Don't install the old npm package to repair the desktop CLI.

## A download failed

Check your internet connection and free disk space. Read the failure in **My Models**, then retry the download. Keep completed models; you do not need to erase all downloads to repair one failure.

## A model won't load or was stopped

Read its error in **Status** or **My Models**. Close memory-heavy applications or choose a smaller recommendation. A model's fit assessment does not reserve that memory against other apps. Longer conversations use more memory; a fresh conversation can help.

Stopping a model does not delete its files. Use **Load model** to try again when enough memory is available.

## My agent can't see or use a model

1. Confirm the model has finished downloading.
2. Check **Connections**. Use **Repair connection** if offered, or **Refresh connection** to refresh a connected agent.
3. Restart or reload the agent and select the Magnitude model.
4. Keep Magnitude running and check Status if requests still fail.

See your [integration guide](/integrations/overview) for specific model-selection and gateway behavior.

## My agent runs in WSL, a container, or on another computer

Connections cannot configure agents there. Use the server's base URL and API key in the agent's configuration. See [Network access](/api/network-access) for connection options and errors, or [Windows and WSL](/api/windows-wsl) for WSL networking.

## My models disappeared after changing the model folder

Changing **Model storage** does not move models. They are still in the previous folder. Move them with the command shown in Settings, or switch back with **Use default**. See [Settings](/settings#model-storage).

## An app update failed

Open **Settings → Application updates** and read the error. Use **Retry update** when offered. You can **Discard download** if you want to remove the retained installer and download it again.

On Linux, installation may require package-manager authorization. Do not quit the installer while it is replacing the app.

## Windows cannot save an update

Versions 0.1.4 and 0.1.5 can fail with “The downloaded update could not be saved.” Install a newer version containing the fix using its Windows installer. The affected versions cannot install the fix through their updater. Deleting the updates folder does not repair it; keep your models and settings.

## There's no tray icon

Some Linux desktops do not provide a supported tray host. Open Magnitude from the applications menu. You can stop it with **Quit Magnitude**.

## Responses are slower than expected

Check **Usage** to distinguish generation speed from time to first token. Loading, longer prompts, concurrent agents, and memory pressure can all affect response time. Try a smaller or faster recommendation and reduce simultaneous work. See [Usage](/models#usage).

## Report a problem

Include your app version, OS, hardware, the model involved, the exact error, and the steps to reproduce it. For Linux desktop issues, include your desktop environment and whether you use X11 or Wayland.

Attach the logs from `~/.magnitude/logs` (`%USERPROFILE%\.magnitude\logs` on Windows): `service.log`, `inference.log`, and `desktop.log`.

Remove credentials, prompts, and private project data from anything you share. Don't delete the entire `.magnitude` folder as a general repair step.

[Report an issue](https://github.com/magnitudedev/magnitude/issues) or ask in [Discord](https://discord.gg/EHt48pPWdC).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.