Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/alber1802/AvaluoVehicular/llms.txt

Use this file to discover all available pages before exploring further.

This page covers the most common issues encountered when setting up, running, and maintaining Avalúo Vehicular — both in local development and in Docker-based production deployments. Issues are organized by symptom: find the error message or behavior that matches your situation, follow the steps, and check the general debug commands at the bottom if the problem persists.
Always check the Laravel log first. Most errors leave a detailed trace in storage/logs/laravel.log. Run the following command to stream the log in real time before trying any fix:
# Local
tail -f storage/logs/laravel.log

# Inside Docker
docker-compose exec app tail -f storage/logs/laravel.log
Symptom: The application shows a 500 error or Laravel logs contain SQLSTATE[HY000] [14] unable to open database file or Permission denied: /var/www/html/database/database.sqlite.Cause: The SQLite file was created on the host by the current user, but the container runs PHP-FPM as www-data. The file must be readable and writable by www-data (UID 33 on Alpine Linux).Fix:
# Set the correct owner and permissions on the mounted file
docker-compose exec app chown www-data:www-data /var/www/html/database/database.sqlite
docker-compose exec app chmod 664 /var/www/html/database/database.sqlite
If the error persists, also fix the parent directory:
docker-compose exec app chown www-data:www-data /var/www/html/database
docker-compose exec app chmod 775 /var/www/html/database
Prevention: Before running docker-compose up for the first time, always create the SQLite file explicitly on the host so Docker mounts it as a file (not a directory):
touch database/database.sqlite
Symptom: The application throws RuntimeException: No application encryption key has been specified or sessions and cookies fail to work after a fresh installation or container rebuild.Cause: APP_KEY in .env / .env.docker is empty or still set to the placeholder value base64:CHANGE_ME_AFTER_KEY_GENERATE.Fix — Local:
php artisan key:generate
Fix — Docker:
docker-compose exec app php artisan key:generate
The generated key is written to the .env file inside the running container. For a persistent key across rebuilds, copy the generated base64:... value into your .env.docker file:
# Get the generated key
docker-compose exec app grep APP_KEY /var/www/html/.env

# Paste it into .env.docker, then rebuild
docker-compose build && docker-compose up -d
Symptom: Laravel logs show failed to open stream: Permission denied for paths under storage/ or bootstrap/cache/. File uploads fail silently, or the application cannot write sessions and cache.Cause: The storage/ and bootstrap/cache/ directories must be writable by the web server user or the CLI user running php artisan serve.Fix:
# Make directories writable
chmod -R 775 storage bootstrap/cache

# If running under a web server (Apache/Nginx with www-data)
chown -R www-data:www-data storage bootstrap/cache

# If running locally with php artisan serve, set your own user
chown -R $(whoami):www-data storage bootstrap/cache
Also ensure the storage symlink exists for public file access:
php artisan storage:link
Symptom: Laravel throws SQLSTATE[HY000]: General error: 1 no such table: sessions (or any other table name), or Inertia pages fail with a 500 because a model query hits a missing table.Cause: Migrations have not been run, or were partially rolled back.Fix — Run pending migrations:
# Local
php artisan migrate

# Docker
docker-compose exec app php artisan migrate --force
Fix — Reset and re-run all migrations (development only — destroys all data):
php artisan migrate:fresh
Fix — Clear stale cached config that might reference a wrong database path:
php artisan optimize:clear
If the sessions or jobs tables are missing specifically, those are created by migrations that ship with Laravel Breeze and must be present for SESSION_DRIVER=database and QUEUE_CONNECTION=database to work.
Symptom: The page loads but all CSS and JavaScript is missing (blank white screen), the browser console shows 404 errors for /build/assets/app-*.js, or Inertia does not mount.Cause A — Production: The Vite build output is missing from public/build/. This can happen if you deployed code without running npm run build, or if the Docker image was not rebuilt after a frontend change.Fix (local):
npm run build
Fix (Docker):
docker-compose build
docker-compose up -d
Cause B — Development: Vite’s dev server is not running, so the manifest file that Inertia references does not exist.Fix:
# Start Vite dev server (keep this running alongside php artisan serve)
npm run dev
Cause C: The public/build/ directory is listed in .gitignore but not being generated in CI. Ensure your build pipeline includes npm ci && npm run build before deploying.
Symptom: docker-compose ps shows the container as Restarting or Exited. The application is unreachable on port 8080.Diagnosis — Check container logs:
docker-compose logs -f
# Or for the last 100 lines
docker-compose logs --tail=100 app
Common causes and fixes:
Error in logsFix
cannot bind to port 8080: address already in useChange the host port in docker-compose.yml ("8081:80") or stop the conflicting process
database is lockedCheck that no other process has the SQLite file open; fix permissions (see above)
No such file or directory: entrypoint.shRun docker-compose build --no-cache to regenerate the image
PHP-FPM fails to startCheck PHP extension errors in logs; ensure the image built successfully
Full rebuild from scratch:
docker-compose down
docker-compose build --no-cache
docker-compose up -d
Symptom: Navigating to a known route like /registro/crear returns a 404 Not Found response, even though the route exists in routes/web.php.Cause A: The route cache contains a stale snapshot that does not include the route.Fix:
php artisan route:clear
# Or in Docker:
docker-compose exec app php artisan route:clear
Cause B: The controller namespace is wrong or the controller file is missing. Verify with:
php artisan route:list --path=registro
Cause C: The authenticated user has not verified their email. All appraisal routes require the verified middleware. The user will be redirected to /verify-email instead of returning 404. Check the user’s email_verified_at column in the database.Cause D: A Spatie permission check (hasPermissionTo(...)) is failing silently and returning early. Check storage/logs/laravel.log for the specific controller and method.
Symptom: Actions that dispatch jobs (e.g., email sending) complete without errors but emails are never sent. The jobs table in the database accumulates unprocessed records.Cause: The Laravel queue worker is not running.Fix — Local:
php artisan queue:listen
# Or for a more robust worker:
php artisan queue:work --tries=3
Fix — Docker: The queue worker should already be managed by Supervisor inside the container. Check its status:
docker-compose exec app supervisorctl status
If the laravel-worker process shows STOPPED or FATAL:
docker-compose exec app supervisorctl start laravel-worker
If the worker keeps crashing, check the Supervisor log and the Laravel log for the underlying error:
docker-compose exec app cat /var/log/supervisor/laravel-worker.log
docker-compose exec app tail -f storage/logs/laravel.log
Symptom: After entering valid credentials, the page redirects back to /login indefinitely without logging in. The browser shows a Too Many Redirects error, or the session does not persist between requests.Cause A: Session table does not exist in the database (SESSION_DRIVER=database requires a sessions table).Fix:
php artisan migrate
# Confirm the sessions table exists:
php artisan tinker --execute="Schema::hasTable('sessions') ? 'OK' : 'MISSING';"
Cause B: APP_KEY is not set or changed after sessions were created, making old session cookies unreadable.Fix:
php artisan key:generate
Then truncate the stale sessions directly (Laravel has no built-in session:flush command):
# Local
php artisan tinker --execute="DB::table('sessions')->truncate();"

# Docker
docker-compose exec app php artisan tinker --execute="DB::table('sessions')->truncate();"
Cause C: Cookie domain mismatch. If SESSION_DOMAIN is set to a domain that does not match the host you are accessing (e.g., you are accessing via IP but SESSION_DOMAIN is set to example.com), the browser will not send the session cookie.Fix: Set SESSION_DOMAIN=null in .env.docker for a default setup, or match it exactly to your APP_URL domain.Cause D: The user’s is_suspended flag is true. Add a temporary Tinker check:
php artisan tinker --execute="App\Models\User::where('email','user@example.com')->value('is_suspended');"
Symptom: Clicking “Generar PDF” triggers an error, returns a 500, or produces a corrupted/empty PDF file. The archivos table record is not created.Cause A: The storage/app/public/pdfReportes/ directory does not exist or is not writable by the web server user.Fix:
mkdir -p storage/app/public/pdfReportes
chmod -R 775 storage/app/public
# Docker:
docker-compose exec app mkdir -p /var/www/html/storage/app/public/pdfReportes
docker-compose exec app chown -R www-data:www-data /var/www/html/storage/app
Cause B: The public storage symlink does not exist.Fix:
php artisan storage:link
# Docker:
docker-compose exec app php artisan storage:link
Cause C: FILESYSTEM_DISK is not set to local, or mccarlosen/laravel-mpdf cannot find its temp directory.Fix: Verify .env.docker:
FILESYSTEM_DISK=local
Cause D: The vehicle referenced by {id} has no MarcaVehiculo record (the firstOrFail() call in ArchivoControler::generarPdf() will throw a ModelNotFoundException). Verify the vehicle’s id_marca references a valid brand in the marca_vehiculos table.

​
General Debug Commands

When the specific issue is unclear, use these commands to reset all compiled caches and inspect the application state. Clear all caches at once: 
# Local
php artisan optimize:clear

# Docker
docker-compose exec app php artisan optimize:clear
Rebuild individual caches (production): 
php artisan config:cache    # Compile all config files into a single cached file
php artisan route:cache     # Compile route list (speeds up routing)
php artisan view:cache      # Pre-compile all Blade templates
Inspect registered routes: 
# All routes
php artisan route:list

# Filter by URI prefix
php artisan route:list --path=registro

# Filter by controller
php artisan route:list --name=avaluo
Check environment and configuration: 
php artisan about              # Show Laravel version, environment, and key config
php artisan env                # Print the current APP_ENV value
php artisan config:show cache  # Show resolved config values for a given namespace
Database inspection: 
# Run a quick query in the REPL
php artisan tinker

# Check a specific table exists
php artisan tinker --execute="Schema::getTables();"
Container shell access: 
# Open an interactive shell inside the Docker container
docker-compose exec app sh

# Run a one-off Artisan command without entering the shell
docker-compose exec app php artisan [command]

Build docs developers (and LLMs) love

Get started for freeTalk to us