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

# Troubleshooting

> When you hit a problem, first note the platform, device, model, and the error message shown in the interface, then work through the categories below.

## Download fails or is interrupted

**macOS**

* Check that the network can reach the model download site.
* On the **Models** page, view the error for the download task; after the network recovers, click **Retry** or **Resume**.
* `E-DL-NET`: network interruption or timeout.
* `E-DL-SRC`: the download source rejected the request or is unreachable; retry later or switch networks.
* `E-DL-DISK`: insufficient disk space; clear space first.

**Windows**

An interrupted download can be resumed. After the network recovers, click **Download** again for the model on the **Models** page, and the app continues from where it stopped.

If it reports a file-size or SHA-256 mismatch, delete the download task and download again. After the download finishes, the app still converts the model, and the model cannot be used until conversion completes.

**iOS / Android**

Models are downloaded on a computer. Check the error output of the download command and whether the files in the model directory are complete.

For more details, see [Security & Installation Warnings](/security-and-installation-warnings).

## Insufficient disk space

* Check the disk that stores models, not just the system drive. macOS stores them under `~/.edge0` by default, and Windows under `%USERPROFILE%\.edge0`.
* Stop any download or conversion in progress first, then clear files you do not need.
* Before deleting a model in the desktop app, click **Unload model** on macOS or **Evict** on Windows, then click **Delete**.
* On macOS, after deleting a model you can run `edge0 gc` with the bundled command-line tool to free files that are no longer used. For the tool's location, see the [macOS Guide](/macos-guide).
* iOS requires checking space on both the Mac and the iPhone; Android requires checking both the computer and the device.

## The model is downloaded but will not load

| Symptom | What to do |
| - | - |
| macOS says the model is not loaded | Confirm the download finished, click **Load model**, and check the service status on the **Service** page |
| macOS reports `E-MEM-LOAD` | Out of memory. Close memory-heavy apps, or switch to 8B |
| macOS reports `E-MODEL-INVALID` | The model file is incomplete or corrupted. Unload and delete it, then download again |
| Windows says the model is not converted | Wait for conversion to finish; if it fails, check `convert-*.log` |
| Windows reports `E-ENGINE-MISSING` | Confirm the engine built successfully; if the repository moved, set `EDGE0_BIN_DIR` as in the [Windows Guide](/windows-guide) |
| Windows cannot find the conversion script | If the repository moved, set `EDGE0_REPO` to the `windows` directory in the repository |
| Windows reports missing Python or NumPy | Confirm `python` is available with NumPy installed, or set `EDGE0_PY` to the correct Python |
| iOS shows **Not included** | The model was not bundled into the current app. Add it to `Models/`, then rebuild and reinstall |
| Android's model list is empty | Confirm the adb import succeeded and that app data was not cleared afterward, then tap **Refresh** |
| Android 8B fails to load | Run `push_models.sh --8b` again and confirm the script completed successfully |

The model file formats differ by platform and are not interchangeable.

## Windows model conversion fails

1. Check `%USERPROFILE%\.edge0\logs\convert-*.log` and find the earliest error.
2. If it is a missing dependency or a path that cannot be found, fix the environment first as in the [Windows Guide](/windows-guide).
3. If it is a missing file or a checksum error, delete the download task and download again.

## The first turn is slow, or it slows down after a while

Loading a model can take time. After it is loaded, the first turn of a new topic and longer inputs may increase the wait before generation begins. For the specifics on Android, see the [Android Guide](/android-guide).

You can try:

* Wait for the current load to finish; do not click load or send repeatedly.
* Start a new chat and test with a short question.
* Close other resource-heavy apps.
* If the device is hot, let it cool down and try again.
* Use 8B first to determine whether the issue is caused by the larger model's resource requirements.

If you also see an error, an unexpected app exit, or no progress for an extended period, continue with the sections below.

## The app crashes or the engine exits

* Note the error message and the time it happened, then reopen the app and load the model.
* Windows: check the latest `engine-*.log`; if it reports a missing engine binary, rebuild the engine.
* macOS: check **Environment Check** on the **Service** page; if it reports a service version mismatch, quit and reopen the app.
* iOS: confirm the model files are complete, reopen the app, and retry with a short question; if it still exits, obtain device logs.
* Android: obtain device logs and look for load errors or crash information.

If the problem persists, prepare the simplest steps to reproduce it and report them.

## Build or installation fails

* **macOS missing Metal compiler**: check Xcode and the Command Line Tools, then run `bash scripts/check-prereqs.sh` again.
* **iOS missing Metal compiler**: run `xcodebuild -downloadComponent MetalToolchain`, then retry.
* **iOS signing fails**: verify the selected Team, unique Bundle Identifier, device trust status, and Developer Mode.
* **Android cannot find the NDK**: install the NDK r28 specified in the guide and set `NDK_DIR`.
* **Android missing native libraries**: run the engine build step successfully first, then build and install the app.
* **The system blocks the app from opening**: see [Security & Installation Warnings](/security-and-installation-warnings).

## Collect diagnostics

**macOS**

Check **Environment Check** and the service status on the **Service** page. Logs are under:

```text theme={null}
~/.edge0/logs/
```

You can also use `edge0 doctor` and `edge0 logs` with the bundled command-line tool; for the tool's location, see the [macOS Guide](/macos-guide).

**Windows**

Check **Environment Check** on the **Service** page. Logs are under:

```text theme={null}
%USERPROFILE%\.edge0\logs\
```

There, `engine-*.log` is the engine log and `convert-*.log` is the model conversion log.

**iOS**

Connect the device in Xcode and reproduce the problem, then view the output in the debug console. When the app exits unexpectedly, you can also view device logs in Xcode's **Devices and Simulators**. Note the time of the error and the model used.

**Android**

With the device connected and authorized, export the relevant logs:

```bash theme={null}
adb logcat -d -v threadtime 'E0LLAMA:V' 'Edge0Load:V' 'AndroidRuntime:E' '*:S' > edge0-android.log
```

The log is saved as `edge0-android.log` in the current directory on the computer. If the log does not cover the moment of the error, reproduce the problem and export again.

Before sharing logs, review and remove sensitive information such as chat content, accounts, paths, device identifiers, and access tokens. For feedback channels, see [FAQ & Support](/faq-and-support).


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