Laravel Doctor — Application Diagnostics Tool

Introduction

laravel/doctor is an official Laravel package that diagnoses common configuration, environment, and infrastructure problems in your application. v0.1.0 was released on July 28, 2026. Each diagnostic is a single check — it inspects one thing, such as whether Laravel can write to its storage directories, and reports one of several statuses. When the repair is safe and deterministic, a diagnostic may also offer a fix. Issues that cannot be repaired safely, such as a failed asset build, are reported with remediation steps instead.

composer require laravel/doctor --dev

Running Doctor

Once installed, the package registers the doctor Artisan command:

php artisan doctor

When a failing diagnostic can be fixed, Doctor reports the problem and prompts before applying the fix:

Storage is writable: The application cannot write to every required storage directory.

 Make the storage directories writable? (yes/no) [yes]

Some fixes offer a choice of repairs instead of a yes/no confirmation. When the default cache store is unreachable, for example, Doctor presents a select list of configured stores that actually work, along with an option to keep the current store and repair it manually. To apply all available fixes without prompting, pass the --fix option:

php artisan doctor --fix

First-party fixes cover deterministic local repairs such as creating a missing .env, generating APP_KEY, disabling production debug mode, adding .env to .gitignore, creating the public storage link, and repairing writable storage directories.

Fixes are only available with the CLI and agent output formats. Doctor rejects --fix with JSON and GitHub report formats so machine-readable reports never mutate the application.

Use --bail to stop after the first diagnostic that fails or errors:

php artisan doctor --bail

Diagnostic Statuses

Every diagnostic returns one of the following statuses:

Status	Meaning	Affects exit code
`pass`	The check succeeded and nothing is wrong.	No
`notice`	Informational context worth surfacing to the developer.	No
`warn`	A potential problem that may not require action.	Only with `--fail-on=warn`
`fail`	The check found a problem that should be resolved.	Yes
`skip`	The check did not apply to the current environment.	No
`error`	The diagnostic threw an exception while running.	Yes

By default, the command exits with a failing status when a diagnostic fails or errors. Use --fail-on=warn to also fail on warnings, or --fail-on=never when Doctor should only report issues.

Selecting Diagnostics

Diagnostics may be selected or excluded by class name, group, package, or package wildcard. Multiple values may be passed by repeating the option or separating values with commas.

php artisan doctor --only=storage

php artisan doctor --only=StorageIsWritable

php artisan doctor --only=vendor/package

php artisan doctor --except=laravel/*

To configure persistent diagnostic selection, publish Doctor’s configuration file:

php artisan vendor:publish --tag=doctor-config

Environment Modes

Some facts about an application cannot be judged on their own. A sync queue connection is sensible on a developer’s machine, but in production it means queued jobs silently run inside web requests. To judge these diagnostics, Doctor resolves the application to one of two modes:

Mode	Expectations
`local`	Active development. Debug mode, `sync` queues, and uncached bootstrap files are normal.
`production`	Serving real traffic. Debug mode is a security risk, queues should run asynchronously, bootstrap files should be cached.

The mode changes the verdict, not just the message. Missing bootstrap caches warn in production but pass locally. Doctor recognizes Laravel’s conventional local, production, and staging environment names out of the box. For custom names, group them in the configuration file:

'environments' => [
    'local' => ['local', 'dev'],
    'production' => ['production', 'staging', 'qa'],
],

Any environment not listed is treated as production, so unfamiliar environments are held to the strictest expectations rather than quietly excused.

Default Diagnostics

Doctor ships with a focused suite of diagnostics:

Environment — .env presence, APP_KEY, PHP version, required extensions, and timezone.
Composer — dependencies installed, autoload optimization, repairable composer.lock problems.
Configuration — config files can be loaded and cached, required values are set, bootstrap cache state matches the environment.
Database — default connection is reachable, SQLite file exists when needed, pending migrations can be applied in local environments.
Cache, queue, scheduler, and session — configured drivers are reachable, sync queues are flagged outside local environments, scheduled tasks are surfaced as a notice.
Storage — default disk is reachable, required directories are writable, storage:link exists when expected.
Security — debug mode matches the environment, .env is gitignored, Composer dependencies are audited.

Creating Diagnostics

A diagnostic extends Laravel\Doctor\Diagnostic and implements a check() method returning a DiagnosticResult. Scaffold one with the make:diagnostic Artisan command:

php artisan make:diagnostic HorizonIsRunning --fixable

The following diagnostic checks whether the application key is set and implements Fixable to generate it automatically:

namespace App\Doctor\Diagnostics;

use Illuminate\Support\Facades\Artisan;
use Laravel\Doctor\Contracts\Fixable;
use Laravel\Doctor\Diagnostic;
use Laravel\Doctor\EnvironmentMode;
use Laravel\Doctor\Results\DiagnosticResult;
use Laravel\Doctor\Results\FixResult;
use Laravel\Doctor\Results\Link;
use Laravel\Doctor\Results\Message;

class ApplicationKeyIsSet extends Diagnostic implements Fixable
{
    public string $name = 'App key is set';

    public string $group = 'environment';

    protected function messages(): array
    {
        return [
            'configured' => 'The application key is configured.',

            'missing' => Message::make(
                summary: 'The application key is not configured.',
                remediation: 'Generate an application key with `php artisan key:generate`.',
                confirmation: 'Generate an application key using `php artisan key:generate`?',
            )->link(Link::docs('encryption')),

            'generated' => 'The application key was generated.',

            'generation-failed' => 'The application key could not be generated.',
        ];
    }

    public function check(): DiagnosticResult
    {
        $key = config('app.key');

        if (is_string($key) && trim($key) !== '') {
            return $this->pass('configured');
        }

        return $this->fail('missing')->fixable(EnvironmentMode::Local);
    }

    public function fix(DiagnosticResult $result): FixResult
    {
        Artisan::call('key:generate', ['--force' => true]);

        $key = config('app.key');

        if (! is_string($key) || trim($key) === '') {
            return $this->fixFailed('generation-failed')
                ->withDetails(trim(Artisan::output()));
        }

        return $this->fixed('generated');
    }
}

When a failure has several valid repairs, declare the choices with fixOptions(). The CLI renders them as a select list, and the chosen value is passed to fix():

return $this->fail('unreachable')
    ->fixable(EnvironmentMode::Local)
    ->fixOptions(['file' => 'File', 'redis' => 'Redis']);

Packages register diagnostics from their service providers using the same API:

use Laravel\Doctor\Facades\Doctor;
use Vendor\Package\Diagnostics\HorizonIsRunning;

public function boot(): void
{
    Doctor::diagnostic(HorizonIsRunning::class);
}

Reports show each diagnostic’s source package next to its name:

[fail] Storage is writable (laravel/doctor): The application cannot write to every required storage directory.
[warn] Horizon is running (laravel/horizon): Horizon is not currently running.

Running Doctor Programmatically

Call Doctor::run() without the Artisan command to get a DiagnosticReport:

use Laravel\Doctor\Facades\Doctor;

$report = Doctor::only('security')
    ->except(SomeDiagnostic::class)
    ->run();

if ($report->hasFailures()) {
    // ...
}

To apply fixes as part of a programmatic run, configure the run with fixUsing:

$report = Doctor::fixUsing(
    fn ($outcome) => $outcome->fixRequiresOption() ? false : true,
)->run();

$report->fixes();

Output Formats and AI Agent Support

Doctor renders readable CLI output by default. JSON and GitHub Actions annotations are also available:

php artisan doctor --format=json

php artisan doctor --format=github

When Doctor detects it is running inside an AI coding agent such as Claude Code or Cursor — using Laravel Agent Detector — it defaults to an agent-optimized format following the Laravel PAO convention:

{"tool":"doctor","result":"failed","diagnostics":27,"failed":1,"warnings":1,"notices":0,"passed":19,"skipped":6,"issues":[{"name":".env file exists","status":"fail","summary":"The application does not have an environment file.","fix":"Run `cp .env.example .env`, then review the copied values.","fixable":true}]}

Issues marked fixable may be fixed by re-running Doctor with --fix. An explicit --format option always overrides detection. To preview agent output outside an agent:

AI_AGENT=test php artisan doctor

Summary

laravel/doctor lets you quickly surface configuration, environment, and infrastructure problems with a single php artisan doctor command. Its deep integration with AI coding agents and the Laravel PAO convention makes it a natural fit for CI/CD pipelines and agent-driven auto-repair workflows.

laravel/doctor repository

Source code and latest updates.

Changelog

Laravel 13

Products

Package Introductions

New Repository Research

Upgrade Guides

Authentication

Frontend

Environment Setup

Laravel Doctor — Application Diagnostics Tool

Introduction

Running Doctor

Diagnostic Statuses

Selecting Diagnostics

Environment Modes

Default Diagnostics

Creating Diagnostics

Running Doctor Programmatically

Output Formats and AI Agent Support

Summary

laravel/doctor repository

​Introduction

​Running Doctor

​Diagnostic Statuses

​Selecting Diagnostics

​Environment Modes

​Default Diagnostics

​Creating Diagnostics

​Running Doctor Programmatically

​Output Formats and AI Agent Support

​Summary

laravel/doctor repository

Introduction

Running Doctor

Diagnostic Statuses

Selecting Diagnostics

Environment Modes

Default Diagnostics

Creating Diagnostics

Running Doctor Programmatically

Output Formats and AI Agent Support

Summary