Link troubleshooting
Record the Link version, operating system and exact error before changing the installation.
Locate the failure
Step 1 of 1: Locate the failure.
Read the Link troubleshooting steps
For an Aventail Link terminal installation, start with:
aventail --version
aventail status
If the command is missing, open a new terminal after installation or use the full executable path. 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 if the service is stopped. If it is running but unresponsive, restart it.
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 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 |
| 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.
Gather diagnostics
In Aventail Link 2.0.0, open Preferences → Device and use Open logs folder or Save diagnostics. See 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:
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.