> ## 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: fleet rollout, updates, and the CLI

## Overview

To diagnose most issues, run:

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

Then reproduce the issue and watch the log.

If the client never arrived on the device in the first place, start with [Fleet and MDM](#fleet-and-mdm) instead.

## Fleet and MDM

<AccordionGroup>
  <Accordion title="Intune reports the app state is unknown (0x87D13B67)">
    The app was added with the wrong app type. `0x87D13B67` is not an install failure — it means Intune has no install status for the app at all, which is also why nothing about Velatir appears in the device logs.

    Velatir installs a background agent under `/Library`, uses install scripts, and places a small stub bundle (not the self-updating host) at `/Applications/Velatir.app`. Intune's **Line-of-business app** type cannot handle that shape: with **Install as managed** set to **Yes** it supports only a package containing a single application that installs into `/Applications`, and either way it detects an install solely by finding an application bundle. A quick way to tell which type you used: if the app's properties show an **Install as managed** field, it is a line-of-business app.

    Delete the app in Intune and add it again as **macOS app (PKG)**, following [Enterprise deployment](/desktop-app/enterprise-deployment#deploy-with-your-mdm). Check the **Included apps** list as you go — an entry of `com.velatir.agent.bootstrap` is the package identifier rather than an application, and while it is listed the install can never be detected.
  </Accordion>

  <Accordion title="Intune reinstalls Velatir on every check-in">
    The detection rule never matches, so Intune keeps concluding the app is missing and installs it again. Confirm it on one device by looking at the install history, which should show one install rather than several in a week:

    ```bash theme={null}
    grep -i velatir /var/log/install.log | tail -20    # macOS install history
    tail -20 /Library/Logs/Velatir/bootstrap.log       # Velatir's own install-time log
    ```

    Fix the rule as described in [Enterprise deployment](/desktop-app/enterprise-deployment#deploy-with-your-mdm): **Included apps** must hold `com.velatir.desktopapp` and not `com.velatir.agent.bootstrap`, with **Ignore app version** set to **Yes**.

    Worth correcting promptly rather than treating as noise. Each reinstall restarts the agent, so devices drop out of the dashboard for a few minutes at a time, and while the agent is down the browser extension on macOS asks users for an ingest key: Microsoft Edge does not deliver managed configuration to extensions on macOS, so the agent is what hands the extension its key.
  </Accordion>

  <Accordion title="velatir status reports it cannot reach VelatirAgent">
    The agent daemon is not running. Ask launchd what it holds for it:

    ```bash theme={null}
    sudo launchctl print system/com.velatir.agent | head -20
    ```

    Then start it:

    ```bash theme={null}
    sudo launchctl bootout system/com.velatir.agent 2>/dev/null
    sleep 3
    sudo launchctl bootstrap system /Library/LaunchDaemons/com.velatir.agent.plist
    sudo launchctl kickstart -k system/com.velatir.agent
    velatir status
    ```

    If `bootstrap` reports `Input/output error`, the label is either still being torn down, in which case waiting a few seconds and repeating clears it, or it is blocked from loading. macOS 13 and later can disable background services and an MDM can control that list, so check both:

    ```bash theme={null}
    sudo launchctl print-disabled system | grep -i velatir
    sfltool dumpbtm | grep -i -A6 velatir
    ```

    A disabled item has to be re-enabled wherever it was disabled: **System Settings → General → Login Items & Extensions** for a user choice, or a Managed Login Items payload from your MDM on a managed fleet.
  </Accordion>

  <Accordion title="The MDM reports a problem, but the device logs show nothing about Velatir">
    The installer never ran, so there is nothing on the device to find. Check in this order:

    ```bash theme={null}
    pkgutil --pkgs | grep -i velatir        # expect com.velatir.agent.bootstrap
    grep -i velatir /var/log/install.log    # did the installer run at all?
    ls -l /Library/Logs/Microsoft/Intune/   # Intune: is the management agent there?
    ```

    No package receipt and nothing in `install.log` puts the problem in the MDM rather than on the device. With Intune, the **Microsoft Intune management agent for macOS** is what runs the installer, and configuration profiles arrive over a different channel — so profiles applying successfully tells you nothing about whether apps can install.

    To rule out the package itself, install it by hand on one device:

    ```bash theme={null}
    sudo installer -pkg Velatir-Bootstrap-macos-arm64.pkg -target /
    velatir status
    ```
  </Accordion>

  <Accordion title="The ingest key profile applied, but the client has no key">
    Check what actually reached the device:

    ```bash theme={null}
    sudo defaults read "/Library/Managed Preferences/com.velatir.agent" ApiKey
    ```

    If that prints nothing, the profile is not delivering the key. The preference domain must be `com.velatir.agent` and the key must be named exactly `ApiKey`. `INGEST_KEY` is the Windows MSI property and has no meaning in a configuration profile, so a profile using that name applies without error and does nothing.

    On Intune, upload the `.mobileconfig` from the [enterprise builder](/desktop-app/enterprise-deployment) as **Devices → Configuration → Create → Templates → Custom** — not a Preference file.

    Set the key directly to get the device working now, then correct the profile:

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

  <Accordion title="Velatir installed, but never started">
    Installing without an ingest key completes successfully, but the agent cannot finish setting itself up — so `/Applications/Velatir.app` is left pointing at nothing and will not open.

    Supply the key. The agent finishes setup on its next check, within a few minutes:

    ```bash theme={null}
    sudo velatir set-api-key --key vltr_ingest_your_api_key_here
    velatir status
    ```

    Across a fleet this usually means the app reached the devices but the profile carrying the ingest key did not. Confirm the profile is scoped to the same devices as the app.
  </Accordion>
</AccordionGroup>

## Traces and coverage

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

    1. **Velatir is running.** `velatir status` should show the host running; `velatir health` should be `Ok`.
    2. **Ingest key configured.** `velatir get-config` should show a masked ingest key. If empty, set it: `velatir set-api-key --key vltr_ingest_...`.
    3. **The activity is in a covered place.** Browser AI is covered by the extension the agent deploys. Desktop apps are reported as installed or launched, not as prompt-and-response traces. See [Overview](/desktop-app/overview).
    4. **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>
</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 that reports the application cannot be found, it was installed without an ingest key and never finished setting itself up — see [Velatir installed, but never started](#fleet-and-mdm).

    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, 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_ingest_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="Velatir cannot reach the backend">
    The agent uses outbound HTTPS. If a firewall, VPN, or zero-trust agent blocks unknown destinations, allow `api.velatir.com` and Velatir's update storage.
  </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="How it works" icon="layers" href="/desktop-app/how-it-works">
    What the desktop client does on each device.
  </Card>
</CardGroup>