Developer troubleshooting
Use this page when the application or its tooling fails during setup, development, or deployment.
First diagnostics
php -v
php -m
php artisan about
php artisan route:list --path=app
php artisan config:show database
php artisan config:show admin
tail -n 200 storage/logs/laravel.log
If you use a non-default PHP binary, put it on PATH or call it explicitly.
Composer or package installation fails
- Confirm PHP meets
composer.json(^8.3). - Run
composer install --no-interaction -vvvfor a detailed error. - Do not commit
auth.json. - If the vendor directory is stale, remove
vendor/andcomposer.lockonly when you intentionally want to resolve fresh versions; normally keep the lock file.
PHP extension missing
Install the extension for your PHP version, then restart PHP-FPM or your local server. The application commonly needs:
bcmath, ctype, curl, dom, fileinfo, gd, intl, mbstring, openssl, pdo_mysql, tokenizer, xml, zip.
Check with:
php -m | sort
“No application encryption key has been specified”
php artisan key:generate
For an existing environment, restore the original APP_KEY from your secret manager. Rotating it can invalidate encrypted data and sessions.
Database connection fails
php artisan config:show database
php artisan tinker --execute 'DB::connection()->getPdo();'
Check DB_CONNECTION, host, port, database, username, and password. For MySQL, confirm the server is running and the database exists.
Migration fails with “Table already exists” or “Duplicate column”
The database was created before the SQL dumps were retired, and one of its objects is missing from the migrations history. The migrations are guarded with Schema::hasTable and Schema::hasColumn, so this only happens when an object was created outside the migrations.
- Back up the database.
- Confirm the failing migration's changes are already present.
- Record it as applied:
php artisan tinker --execute 'DB::table("migrations")->insert(["migration" => "2026_10_01_000100_create_organization_tables", "batch" => ((int) DB::table("migrations")->max("batch")) + 1]);'
- Rerun
php artisan migrate --force.
Never mark a migration as applied unless its tables, columns, and indexes exist. Replace the example migration name with the one that failed.
Sessions, cache, or queues fail
The migrations should provide sessions, cache, cache_locks, and jobs.
php artisan migrate --force
php artisan config:clear
php artisan optimize:clear
If you use Redis, install the PHP Redis extension or set REDIS_CLIENT=predis and install predis/predis.
Vite manifest error
“Unable to locate file in Vite manifest” means the compiled assets are missing.
npm ci
npm run build
For development, run npm run dev and keep it running. If you changed vite.config.mjs, restart Vite.
Dark-mode styles are missing
- Confirm
resources/css/app.cssis included in the Vite inputs. - Rebuild assets.
- The theme uses the
darkclass on<html>, set by the header toggle and the inline script in the layouts. - Check that your Blade view uses the
dark:variants or theui-*classes.
Tenant errors
TenantNotResolvedException or empty results usually mean no company is active.
- Sign in through a guard the request resolves (
weborportal). - Confirm the user has a
company_idor acompany_usermembership. - For console commands, wrap work in
TenantContext::run($companyId, fn () => ...)or usewithoutTenant()for intentional platform queries. - Do not read
request()->user()->company_iddirectly; useTenantContext.
See Multi-tenancy.
Queue jobs are not processing
php artisan queue:work --sleep=3 --tries=3
php artisan queue:failed
- Confirm
QUEUE_CONNECTION=database. - Confirm the
jobstable exists. - Check
storage/logs/laravel.log. - In production, confirm the worker service is running.
- After a deploy, restart the worker so it loads the new code.
Payroll engine check fails
php artisan payroll:engine --check
ls -l bin/payroll-engine
make -C payroll-engine build
- Confirm the binary is executable.
- Confirm the database is reachable.
- Confirm
PAYROLL_ENGINE_BINARYpoints to the correct path. - Set
PAYROLL_ENGINE_DRIVER=phponly as a temporary fallback. It is parity-locked to the Go engine; runphp artisan payroll:engine --parityto confirm the driver reproduces the committed corpus.
Reverb or WebSockets fail
- Confirm
REVERB_APP_ID,REVERB_APP_KEY, andREVERB_APP_SECRET. - Confirm
BROADCAST_CONNECTION=reverb. - Run
php artisan reverb:start. - Proxy the WebSocket port through Nginx or your load balancer.
- Restart the queue worker after changing broadcast configuration.
Playwright cannot reach the app
- Start the app or set
E2E_BASE_URLto a reachable environment. - Confirm the URL responds:
curl -I "$E2E_BASE_URL/app/login". - Run
npx playwright installonce per machine. - The global setup seeds an isolated company; if seeding fails, run
php artisan testing:seed-e2e-companymanually and read the error. - If tests fail with stale data, run
php artisan testing:purge-e2e-companyand retry.
Storage or uploads fail
php artisan storage:link
ls -la storage/app/public public/storage
- Confirm the web server user can write to
storageandbootstrap/cache. - Check
FILESYSTEM_DISKandMEDIA_DISK. - If using S3, confirm the bucket, region, credentials, and IAM permissions.
- In the AWS image, the instance role supplies S3 access; do not put long-lived keys in
.env.
Behind an ALB, redirects or secure cookies are wrong
Set:
TRUSTED_PROXIES=*
SESSION_SECURE_COOKIE=true
The application reads TRUSTED_PROXIES in bootstrap/app.php. Only use * when the app is not directly reachable from the internet.
Still stuck
Collect:
- the exact command and output
- PHP, MySQL, Node, and Go versions
- the relevant
storage/logs/laravel.loglines - whether the problem happens locally, in CI, or only in production
Remove secrets and personal data before sharing logs.