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.

Composer

php artisan optimize:clear
tail -f storage/logs/laravel.log

Data isn’t showing up in the dashboard

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

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:

php artisan queue:work        # or: php artisan horizon

Under Docker, check the worker container: docker compose ps and docker compose logs horizon.

The client can't reach the server

From the monitored application’s host, confirm LARAOWL_SERVER_URL is reachable and returns a response:

curl -I https://your-laraowl-server.com

Check for firewalls, DNS, or a self-signed certificate blocking the request.

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.

Failed jobs are piling up

If ingestion jobs are failing, inspect and retry them:

php artisan queue:failed
php artisan queue:retry all

Check storage/logs/laravel.log (or the Horizon dashboard) for the underlying exception.

The dashboard doesn’t update in real time

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

Reverb isn't running

Start (or restart) the WebSocket server:

php artisan reverb:start

Under Docker, check the reverb container logs: docker compose logs -f reverb.

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.

Broadcasting isn't set to Reverb

Confirm BROADCAST_CONNECTION=reverb in .env, then clear the config cache.

Common errors

Unable to locate file in Vite manifest

Frontend assets haven’t been compiled. Build them:

npm run build

No application encryption key has been specified

APP_KEY is empty. Generate one:

php artisan key:generate

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.

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.

FAQs

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.

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 is running.

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.

How do I create additional users?

Invite team members from within the dashboard (team invitations are sent by email — configure mail first). To create a user from the CLI, use Tinker as shown in the installation guide.

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.

Still stuck?

Open an issue on the GitHub repository with your LaraOwl version, install method (Docker or Composer), and the relevant log output.