Skip to main content

Laravel queue job errors next to web errors

Install sentry/sentry-laravel and set SENTRY_LARAVEL_DSN=http://sentry@127.0.0.1:8000/1 in .env. When a queued job throws, its exception lands in Buggregator on the same page as your web errors. The breadcrumb "Processing queue job" names the job class, the queue, the connection and the attempt number.

Steps

1. Start Buggregator

bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  ghcr.io/buggregator/server:latest

2. Install the Sentry SDK

bash
composer require sentry/sentry-laravel

In Laravel 11 and newer, let Sentry handle exceptions in bootstrap/app.php:

php
use Illuminate\Foundation\Configuration\Exceptions;
use Sentry\Laravel\Integration;

->withExceptions(function (Exceptions $exceptions) {
    Integration::handles($exceptions);
})

3. Set the DSN

One line in .env. The worker reads the same file. In Docker Compose, use the service name: http://sentry@buggregator:8000/1.

dotenv
SENTRY_LARAVEL_DSN=http://sentry@127.0.0.1:8000/1

4. Restart the worker

A running worker keeps the config it started with.

bash
php artisan queue:restart
php artisan queue:work

5. Let a job fail

Dispatch a job that throws. Open http://127.0.0.1:8000. The exception shows its stack trace, and the breadcrumbs show the job it came from. Web errors and job errors sit in one list.

Why it works

Laravel reports the exception a job throws, and the Sentry SDK sends it like any other error. The SDK clears breadcrumbs when a job starts and adds one with the job's details, so the error shows only what happened in that job. It also sends the event as soon as the job fails, so a long-running worker does not hold it back.

Checked on with Buggregator v2.13.0

Setup in 60 seconds

No registration. No account. Start it and point your app at it.

1

Start Buggregator

One file, installed with one command. The web UI opens on port 8000. Prefer containers? Use the Docker tab.

$ curl -fsSL https://raw.githubusercontent.com/buggregator/server/master/scripts/install.sh | sh
$ HTTP_ADDR=127.0.0.1:8000 \
  SMTP_ADDR=127.0.0.1:1025 \
  VAR_DUMPER_ADDR=127.0.0.1:9912 \
  MONOLOG_ADDR=127.0.0.1:9913 \
  PROXY_ADDR=127.0.0.1:8080 \
  ~/.local/bin/buggregator

The script picks the file for your CPU: Intel/AMD or ARM.

One file for Linux, macOS and Windows, about 40 MB. Nothing else to install.

This run line keeps it on this computer. Without the *_ADDR settings it listens on all network interfaces

Rather not run a script? Download the file yourself

Runs on Windows, macOS and Linux, on Intel/AMD and ARM.

Prefer not to do it yourself? Your AI agent can set Buggregator up for you