Debugging

The skeleton ships exactly the tools needed to debug a vanilla Laravel app. None of them are framework-specific to this repo — they're all standard Laravel tooling — but the configuration to surface them is already wired in.

Tail the logs

The fastest answer to "what just broke?" is the log. Default channel is stack → single → storage/logs/laravel.log.

tail -f storage/logs/laravel.log

For a richer view, use the bundled laravel/pail:

php artisan pail

Pail formats each log entry, color-codes levels, and follows the file in real time. The composer dev script runs it in one of its four panes by default.

To filter:

php artisan pail --level=error
php artisan pail --filter="User"

Inspect exceptions

APP_DEBUG=true (set in .env.example for local) makes the framework render full stack traces with the Ignition error page. Production should run with APP_DEBUG=false.

If an exception is being swallowed somewhere — common with queued jobs and event listeners — register a reportable callback inside bootstrap/app.php:

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->report(function (\Throwable $e) {
        \Log::error('Unhandled exception', [
            'exception' => $e,
        ]);
    });
})

Note that this is additive — Laravel still runs its default reporters too.

Debug Eloquent

\DB::listen(function ($query) {
    \Log::debug($query->sql, [
        'bindings' => $query->bindings,
        'time' => $query->time,
    ]);
});

Drop that into App\Providers\AppServiceProvider::boot(). Every query gets logged.

For one-off inspection, \Log::debug($model->toArray()) and dd($model) are still the workhorses.

Drop into Tinker

php artisan tinker

Tinker (laravel/tinker is in composer.json requires) gives you a live REPL with the application booted. Useful for poking at the DB, instantiating models, calling helpers:

> User::create(['name' => 'Alice', 'email' => 'a@example.com', 'password' => 'secret']);
> User::where('email', 'a@example.com')->first();
> exit

Inspect routes

php artisan route:list
php artisan route:list --columns=method,uri,name,action
php artisan route:list --path=user

In a fresh skeleton this is short — one web route (GET / → welcome) and one health route (GET /up). As soon as you add controllers it grows fast.

Inspect config

php artisan config:show app
php artisan config:show database.connections.sqlite

config:show prints the resolved config array with values from .env already merged in. If you suspect a stale cache:

php artisan config:clear        # remove bootstrap/cache/config.php
php artisan optimize:clear      # remove every cached file (config, routes, views, events)

Inspect environment

php artisan about

Prints a table of the application name, env, debug status, URL, timezone, locale, all configured drivers, and PHP/Composer versions. Useful as a "is the env even set up correctly?" check.

php artisan env       # just APP_ENV

Common errors and runbooks

"No application encryption key has been specified"

php artisan key:generate

The composer setup script does this automatically; you're seeing this because .env was created manually or key:generate was skipped.

"could not find driver" on DB connection

Missing PHP extension for the database driver in config/database.php. The CI matrix installs pdo, sqlite, pdo_sqlite — for MySQL/PG you need pdo_mysql or pdo_pgsql enabled.

php -m | grep pdo

Vite assets 404 in dev

Illuminate\Foundation\ViteManifestNotFoundException: Vite manifest not found

public/build/manifest.json doesn't exist (you haven't run npm run build) and public/hot doesn't exist (you haven't run npm run dev). Welcome view's fallback inline stylesheet kicks in for / but any other view using @vite will fail.

Fix by running npm run dev (development) or npm run build (production).

Maintenance mode "stuck"

If storage/framework/maintenance.php exists, every request returns 503. Created by php artisan down, removed by php artisan up. If up doesn't clear it (file permissions, etc.):

rm storage/framework/maintenance.php

Fresh CI failure on a PR

The CI matrix (8.3, 8.4, 8.5) sometimes catches a PHP 8.5 deprecation that doesn't show up locally. Check config/database.php's Pdo\Mysql::ATTR_SSL_CA branch — that's the canonical example of how to forward-compat 8.5.

Debugging the queue

The default queue connection is database, which means jobs are rows in the jobs table. To see what's pending:

php artisan queue:listen --tries=1 --timeout=0
# or, if you just want to drain once:
php artisan queue:work --once

Failed jobs land in failed_jobs:

php artisan queue:failed              # list failures
php artisan queue:retry <id|all>      # retry a failure
php artisan queue:flush               # clear the failed table

Debugging Blade

If a view renders weirdly, the cached compiled file is in storage/framework/views/<hash>.php. Read it to see the actual PHP that the framework executes. To reset:

php artisan view:clear

Step-debugging with Xdebug

Install Xdebug (locally) and configure it for develop, debug modes. With the composer dev script running php artisan serve, point your IDE's Xdebug listener at port 9003 and add a breakpoint. Every request through php artisan serve is a fresh process, so breakpoints hit reliably without the persistent-connection issues you can run into with FPM.