# Link troubleshooting

Source: [https://docs.aventail.co.uk/docs/link-app/troubleshooting](https://docs.aventail.co.uk/docs/link-app/troubleshooting)

Record the Link version, operating system and exact error before changing the installation.

### Locate the failure

Process overview; detailed actions and examples are below.

1.  **Locate the failure**
    
    Start with the device and exact error. Keep network protections enabled while diagnosing.
    
    -   Local service: Check the installed version and service status
    -   Management connection: Check account and outbound connectivity
    -   Model endpoint: Test serving separately

**Read the Link troubleshooting steps**

For an Aventail Link terminal installation, start with:

```bash
aventail --version
aventail status
```

If the command is missing, open a new terminal after installation or use the [full executable path](https://docs.aventail.co.uk/docs/link-app/file-locations). On macOS desktop that is `"$HOME/Library/Application Support/Aventail-Link/aventail"`. Headless Link has no menu-bar icon.

`NeedsSetup` means the service still needs onboarding. Record the version, operating system and exact error before making changes. For Locai Link (Legacy Aventail) 1.x, use `locai status` instead.

## Agent offline or menu icon missing

For Aventail Link 2.0.0, use `aventail service start` with the [full executable path](https://docs.aventail.co.uk/docs/link-app/file-locations) if the service is stopped. If it is running but unresponsive, [restart it](https://docs.aventail.co.uk/docs/getting-started/restarting-loc-ai-link).

For Locai Link (Legacy Aventail) 1.x, open the legacy app, labelled **Locai Link**, from Applications or use `locai start`. That application does not operate the new Aventail service.

Local health, the connection to Control and model serving are separate states. In Aventail Preferences, check **Device → Health** and **Control link**. The older 1.x app has a separate **Agent** panel.

## Network disconnected

In Aventail Link 2.0.0, connection status is **Preferences → Device → Control link**. The separate Network panel belongs to Locai Link (Legacy Aventail) 1.x.

Use [connection troubleshooting](https://docs.aventail.co.uk/docs/troubleshooting/common-issues) to check the API and messaging endpoints. A failed TCP test can indicate DNS, routing, firewall or service problems; it does not identify the cause by itself.

Ask your network administrator to investigate certificate or proxy errors. Keep security controls enabled while diagnosing them.

## Registration or account problems

| Symptom | Next action |
| --- | --- |
| Expired, used or rejected key | Generate a fresh key in the intended Control environment, keep its `LINK_API_BASE`, and repeat registration |
| Installer URL returns 404 | Check the selected release channel; it may not have a published release yet |
| Download or checksum failure | Check access to the release hosts and retry from the official URL; do not skip checksum verification |
| Device limit reached | Check account capacity and existing devices before trying again |
| Wrong account after approval | Check the default browser's signed-in account and Control environment; see [re-registration](https://docs.aventail.co.uk/docs/link-app/re-register) |
| Registered but offline | Check the agent and management connection before registering again |

## Model download or serving problems

Record the model, device, available disk space and error. Check **Notifications → Deployments** in Control or **Preferences → Models**.

If the download has failed, resolve the reported cause and use the available retry/deploy action. For a stalled download, inspect progress before cancelling. Avoid repeated deployments or manual file deletion.

If installation succeeded but chat fails, [check the serving endpoint](https://docs.aventail.co.uk/docs/getting-started/run-first-interface#if-the-request-fails).

## Gather diagnostics

In Aventail Link 2.0.0, open **Preferences → Device** and use **Open logs folder** or **Save diagnostics**. See [file locations](https://docs.aventail.co.uk/docs/link-app/file-locations) to inspect the logs directly.

**Locai Link (Legacy Aventail) 1.x diagnostics**

Locai Link (Legacy Aventail) 1.x provides **Preferences → Advanced → Logs** and these local diagnostics:

```bash
curl --fail --silent --show-error --max-time 10 http://127.0.0.1:20505/healthz
curl --fail --silent --show-error --max-time 10 http://127.0.0.1:20505/models
```

Include relevant error lines, timestamps and steps to reproduce. Remove credentials and personal data before sending diagnostics to support.