Troubleshooting

Solutions to common issues encountered during Auto Commerce installation.

Installation Wizard Issues

Wizard Not Loading

Symptom: The installation wizard page doesn't load or shows a blank screen.

Solutions:

1. Verify the API is reachable by visiting {API_URL}/api/v1/install/status
2. Check that NEXT_PUBLIC_API_URL is correctly set in the frontend .env
3. Verify CORS is configured to allow requests from your frontend domain
4. Check browser console for JavaScript errors

Wizard Redirects to Login

Symptom: Instead of showing the wizard, you're redirected to the login page.

Cause: The application thinks it's already installed.

Solutions:

1. Check if storage/.installed file exists and delete it
2. Verify the database is empty or drop and recreate it
3. Clear application cache: php artisan cache:clear

Database Issues

Database Connection Failed

Symptom: "SQLSTATE[HY000] [2002] Connection refused" or similar.

Solutions:

1. Verify database credentials in .env
2. Ensure the database server is running
3. Check if the database port is accessible
4. For Docker: ensure containers are on the same network

# Test database connection
php artisan db:show

Migration Errors

Symptom: Migrations fail with syntax or constraint errors.

Solutions:

1. Ensure you're using PostgreSQL 14+ or MySQL 8+
2. Check if previous migrations partially ran: php artisan migrate:status
3. For fresh start: php artisan migrate:fresh (deletes all data)

Redis Issues

Redis Connection Failed

Symptom: "Connection refused" or "NOAUTH" errors for Redis.

Solutions:

1. Verify Redis is running: redis-cli ping
2. Check Redis password matches .env configuration
3. For Docker: ensure Redis container is on the same network
4. Check Redis port (default 6379) is not blocked

# Test Redis connection
redis-cli -h 127.0.0.1 -p 6379 ping

Authentication Issues

Passport Keys Error

Symptom: "Key path does not exist or is not readable" for OAuth.

Cause: Laravel Passport encryption keys are missing.

Solutions:

1. Generate keys manually:

   php artisan passport:keys
   

2. Verify keys exist:

   ls -la storage/oauth-*.key
   

3. Set correct permissions:

   chmod 600 storage/oauth-private.key
   chmod 644 storage/oauth-public.key
   

Personal Access Client Missing

Symptom: "Personal access client not found" when generating tokens.

Solution:

php artisan passport:client --personal --name="Auto Commerce Personal Access Client"

Permission Issues

Permission Denied Errors

Symptom: "Permission denied" when writing to storage or cache directories.

Solutions:

1. Set correct ownership:

   chown -R www-data:www-data storage bootstrap/cache
   

2. Set correct permissions:

   chmod -R 775 storage
   chmod -R 775 bootstrap/cache
   

Log File Permission Errors

Symptom: Cannot write to log files.

Solution:

touch storage/logs/laravel.log
chmod 664 storage/logs/laravel.log
chown www-data:www-data storage/logs/laravel.log

Queue Worker Issues

Jobs Not Processing

Symptom: Background jobs remain in queue and don't process.

Solutions:

1. Verify queue worker is running:

   # Docker
   docker compose ps
   
   # Manual
   systemctl status autocom-queue
   

2. Check worker logs for errors
3. Restart the queue worker:

   php artisan queue:restart
   

Frontend Issues

API Requests Failing

Symptom: Frontend can't communicate with the API.

Solutions:

1. Verify NEXT_PUBLIC_API_URL is set correctly
2. Check CORS configuration allows your frontend origin
3. Ensure the API is accessible from the frontend's network
4. Check for SSL/TLS issues if using HTTPS

Build Errors

Symptom: npm run build fails.

Solutions:

1. Clear npm cache: npm cache clean --force
2. Delete node_modules and reinstall: rm -rf node_modules && npm ci
3. Check Node.js version (18+ required): node --version

Docker-Specific Issues

Container Won't Start

Symptom: Docker containers fail to start or keep restarting.

Solutions:

1. Check logs: docker compose logs -f
2. Verify .env files exist and are configured
3. Check port conflicts: netstat -tlnp | grep -E '(3000|8000)'
4. Rebuild containers: docker compose build --no-cache

Volume Permission Issues

Symptom: Permission denied errors inside Docker containers.

Solution: Add user mapping in docker-compose.yml:

services:
  app:
    user: "1000:1000"

Getting Help

If you're still experiencing issues:

1. Check the application logs: storage/logs/laravel.log
2. Review Docker logs: docker compose logs
3. Enable debug mode temporarily: APP_DEBUG=true in .env
4. Search existing issues on GitHub
5. Open a new issue with detailed error messages and environment info