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

# Troubleshooting

> Diagnose and resolve common issues with the Velatir desktop client: interception, certificates, updates, and the CLI

## Overview

To diagnose most issues, run:

```bash theme={null}
velatir status
velatir logs --host -f
```

Then reproduce the issue in a supported AI application and watch the log.

## Interception

<AccordionGroup>
  <Accordion title="Traces are not appearing in the dashboard">
    Confirm in this order:

    1. **Velatir is running.** `velatir status` should show capture active.
    2. **Ingest key configured.** `velatir get-config` should show a masked ingest key. If empty, set it: `velatir set-api-key --key vltr_...`.
    3. **The application is supported.** Velatir captures only supported applications. See [Overview](/desktop-app/overview#supported-applications).
    4. **Certificate trust.** Some runtimes use their own trust store. See [Certificate not trusted by a specific runtime](#certificate-not-trusted-by-a-specific-runtime).
    5. **Network reachability.** The device must reach `api.velatir.com`: `curl -I https://api.velatir.com`.

    If all check out, run `velatir logs --host -f` while reproducing and share the output with support.
  </Accordion>

  <Accordion title="Some applications are captured, others are not">
    This is expected. Velatir only captures supported AI applications; everything else is passed through untouched.

    To request coverage for an application, contact your account team with the application name, vendor, operating system, and the AI provider it talks to (for example, "Editor X on Windows talks to api.anthropic.com").
  </Accordion>

  <Accordion title="Capture will not start">
    **Windows:** usually the install did not complete correctly. Reinstall the MSI with administrator elevation. If it persists, run `velatir logs -f` while attempting `velatir start` and capture the error.

    **macOS:** usually the system extension has not been approved. Open **System Settings → General → Login Items & Extensions → Network Extensions** and confirm **Velatir** is enabled. See [Permissions](/desktop-app/permissions#macos).
  </Accordion>
</AccordionGroup>

## Certificates

<AccordionGroup>
  <Accordion title="Certificate not trusted by a specific runtime">
    Browsers and most native apps use the operating system trust store and pick up the Velatir CA automatically. A few runtimes use their own trust store and need explicit configuration.

    **Node.js**

    ```bash theme={null}
    export NODE_EXTRA_CA_CERTS=/path/to/velatir-ca.crt
    ```

    On macOS the installer sets this automatically. Restart any Node.js process that was running before the install.

    **Python (`requests`, `urllib`)**

    ```bash theme={null}
    export SSL_CERT_FILE=/path/to/velatir-ca.crt
    export REQUESTS_CA_BUNDLE=/path/to/velatir-ca.crt
    ```

    **JVM**

    Import the Velatir CA into the JVM truststore:

    ```bash theme={null}
    keytool -importcert -trustcacerts \
      -keystore "$JAVA_HOME/lib/security/cacerts" \
      -storepass changeit \
      -alias velatir \
      -file /path/to/velatir-ca.crt
    ```

    **curl**

    `curl` follows the OS trust store on macOS and Windows. On Linux, point it explicitly:

    ```bash theme={null}
    curl --cacert /path/to/velatir-ca.crt https://...
    ```
  </Accordion>

  <Accordion title="Certificate pinned by the application">
    Some applications only trust one specific certificate and reject any other. There is no workaround; Velatir detects these connections and passes them through unmodified.

    If a pinned application is critical to your compliance workflow, contact your account team about coverage options.
  </Accordion>
</AccordionGroup>

## Agent and Host

<AccordionGroup>
  <Accordion title="`velatir status` reports the agent is unreachable">
    This means the Velatir process is not running.

    **Windows:** it runs as the **VelatirAgent** service. Start it with `sc start VelatirAgent` from an elevated prompt, or restart the device. If the service is missing, reinstall the MSI.

    **macOS:** relaunch **Velatir** from Applications, or run `open /Applications/Velatir.app`.

    If it keeps disappearing, run `velatir logs -f` (it reconnects once the client comes up) and share the output with support.
  </Accordion>

  <Accordion title="Velatir keeps restarting">
    Velatir restarts itself within 30 seconds if it stops unexpectedly. Frequent restarts usually mean a problem. Inspect the log:

    ```bash theme={null}
    velatir logs --host
    ```

    Common causes: an invalid ingest key, a bad bring-your-own CA password, or (rarely) a failed update. Reset to a known-good state by reapplying the ingest key:

    ```bash theme={null}
    velatir set-api-key --key vltr_your_api_key_here
    ```
  </Accordion>

  <Accordion title="A second launch does nothing">
    Velatir only runs one copy at a time, so an accidental second launch exits silently. This is expected. To restart it:

    ```bash theme={null}
    velatir host restart
    ```
  </Accordion>
</AccordionGroup>

## Updates

<AccordionGroup>
  <Accordion title="`velatir update` reports no new version, but I expected one">
    Velatir checks for updates periodically. To force a check now:

    ```bash theme={null}
    velatir update
    velatir update --apply
    ```

    If the version is still older than expected, or you use a tenant-specific update channel, contact support.
  </Accordion>

  <Accordion title="An update applied but the version did not change">
    A failed update stays on the previous version. Inspect the log:

    ```bash theme={null}
    velatir logs -f
    ```

    A common cause is insufficient disk space. Free up space and retry with `velatir update --apply`.
  </Accordion>
</AccordionGroup>

## Networking

<AccordionGroup>
  <Accordion title="VPN connected after Velatir started, and now things are odd">
    Velatir re-binds on its own when the network changes, so this usually resolves within seconds. If it does not:

    ```bash theme={null}
    velatir restart
    ```

    See [VPN compatibility](/desktop-app/vpn-compatibility).
  </Accordion>

  <Accordion title="QUIC / HTTP/3 connectivity unusual">
    On Windows, Velatir keeps known AI hosts on a connection it can observe; other traffic (including HTTP/3 to non-AI sites) is untouched, so this rarely causes visible issues. On macOS, QUIC is not captured at all.
  </Accordion>
</AccordionGroup>

## Getting Help

When you contact support, attach:

```bash theme={null}
velatir status --json > status.json
velatir version > version.txt
velatir logs > agent.log
velatir logs --host > host.log
```

These four files describe the state of the desktop client and let support reproduce most issues without further round trips.

## Next Steps

<CardGroup cols={2}>
  <Card title="FAQ" icon="circle-help" href="/desktop-app/faq">
    Quick answers to common questions.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/desktop-app/cli">
    Full command surface for diagnosing and recovering.
  </Card>

  <Card title="Permissions" icon="shield-check" href="/desktop-app/permissions">
    What the app needs from the operating system, and why.
  </Card>

  <Card title="VPN compatibility" icon="globe" href="/desktop-app/vpn-compatibility">
    Detail on coexistence with corporate VPNs.
  </Card>
</CardGroup>