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

# Troubleshooting & FAQs

> Diagnose and fix common LaraOwl issues.

Most problems fall into three buckets: **data isn't arriving**, **the dashboard isn't updating in real time**, or **stale cache after a change**. Start here.

## First steps

Before digging in, clear cached state and check the logs — this resolves a large share of issues, especially after an update or `.env` change.

<CodeGroup>
  ```bash Composer theme={null}
  php artisan optimize:clear
  tail -f storage/logs/laravel.log
  ```

  ```bash Docker theme={null}
  docker compose exec app php artisan optimize:clear
  docker compose logs -f app horizon reverb
  ```
</CodeGroup>

## Data isn't showing up in the dashboard

Telemetry is processed asynchronously through the queue, so a stopped worker is the most common cause.

<AccordionGroup>
  <Accordion title="The queue worker isn't running">
    Ingested data sits in the queue until a worker processes it. Confirm a worker is active and restart it if not:

    ```bash theme={null}
    php artisan queue:work        # or: php artisan horizon
    ```

    Under Docker, check the worker container: `docker compose ps` and `docker compose logs horizon`.
  </Accordion>

  <Accordion title="The client can't reach the server">
    From the **monitored** application's host, confirm `LARAOWL_SERVER_URL` is reachable and returns a response:

    ```bash theme={null}
    curl -I https://your-laraowl-server.com
    ```

    Check for firewalls, DNS, or a self-signed certificate blocking the request.
  </Accordion>

  <Accordion title="The API token is wrong or revoked">
    A mismatched token causes the server to reject ingestion. Re-copy the token from **Project Settings → API Keys** and confirm `LARAOWL_TOKEN` in the monitored app matches exactly, then clear that app's config cache.
  </Accordion>

  <Accordion title="Failed jobs are piling up">
    If ingestion jobs are failing, inspect and retry them:

    ```bash theme={null}
    php artisan queue:failed
    php artisan queue:retry all
    ```

    Check `storage/logs/laravel.log` (or the Horizon dashboard) for the underlying exception.
  </Accordion>
</AccordionGroup>

## The dashboard doesn't update in real time

Real-time updates depend on the Reverb WebSocket server and correct `VITE_` build variables.

<AccordionGroup>
  <Accordion title="Reverb isn't running">
    Start (or restart) the WebSocket server:

    ```bash theme={null}
    php artisan reverb:start
    ```

    Under Docker, check the `reverb` container logs: `docker compose logs -f reverb`.
  </Accordion>

  <Accordion title="The browser can't open the WebSocket">
    Open your browser's developer console and look for a failed WebSocket connection. Confirm:

    * `VITE_REVERB_HOST` points at your WebSocket hostname (for example `ws.your-domain.com`).
    * DNS for that hostname resolves and its SSL certificate is valid.
    * `VITE_REVERB_SCHEME` is `https`/`wss` in production.

    Remember: `VITE_` variables are baked in at build time — rebuild assets (`npm run build`) or rebuild the Docker image after changing them.
  </Accordion>

  <Accordion title="Broadcasting isn't set to Reverb">
    Confirm `BROADCAST_CONNECTION=reverb` in `.env`, then clear the config cache.
  </Accordion>
</AccordionGroup>

## Common errors

<AccordionGroup>
  <Accordion title="Unable to locate file in Vite manifest">
    Frontend assets haven't been compiled. Build them:

    ```bash theme={null}
    npm run build
    ```
  </Accordion>

  <Accordion title="No application encryption key has been specified">
    `APP_KEY` is empty. Generate one:

    ```bash theme={null}
    php artisan key:generate
    ```
  </Accordion>

  <Accordion title="SQLSTATE / could not connect to database">
    Verify your `DB_*` credentials. Under Docker, `DB_HOST` must be the `db` service name, not `127.0.0.1`. Confirm the database container is healthy: `docker compose ps`.
  </Accordion>

  <Accordion title="Changes to .env aren't taking effect">
    Cached configuration overrides `.env`. Clear it with `php artisan optimize:clear`. For `VITE_` variables, rebuild the frontend as well.
  </Accordion>
</AccordionGroup>

## FAQs

<AccordionGroup>
  <Accordion title="Can I monitor multiple applications with one server?">
    Yes. Create a separate **project** for each application. Each project gets its own dashboard, API token, alert rules, and retention policy.
  </Accordion>

  <Accordion title="How do I control how long data is kept?">
    Set a per-project retention policy in **Project Settings** (1, 3, 7, 14, 30, 60, 90 days, or never delete). A daily scheduled job prunes data automatically — make sure the [scheduler](/installation#scheduler-cron-entry) is running.
  </Accordion>

  <Accordion title="Does the client package slow down my application?">
    Impact is minimal. Captured data is sent to the server, which queues it immediately and responds `200 OK` — all processing and broadcasting happen in the background on the LaraOwl server, not in your app's request lifecycle.
  </Accordion>

  <Accordion title="How do I create additional users?">
    Invite team members from within the dashboard (team invitations are sent by email — configure [mail](/configuration#mail-for-alerts-and-team-invitations) first). To create a user from the CLI, use Tinker as shown in the [installation guide](/installation#docker).
  </Accordion>

  <Accordion title="Why is public registration disabled?">
    `ALLOW_REGISTRATION` defaults to `false` so your instance stays private. Set it to `true` only if you intend to allow open sign-ups.
  </Accordion>
</AccordionGroup>

## Still stuck?

Open an issue on the [GitHub repository](https://github.com/laraowl/laraowl/issues) with your LaraOwl version, install method (Docker or Composer), and the relevant log output.