Skip to main content

Troubleshooting

Purpose​

This page documents common technical issues, diagnostic commands, and standard resolution steps for Maqsafy services.

Troubleshooting Rules​

  • Do not include real passwords.
  • Do not include access tokens.
  • Do not include private keys.
  • Do not include customer personal data.
  • Remove sensitive data from logs before documenting.
  • Document only confirmed root causes.
  • Use placeholders for domains, IPs, credentials, and user identifiers.

Troubleshooting Template​

Use this structure for every issue:

FieldDescription
IssueShort issue description
SymptomsWhat the user or system shows
Possible CauseTechnical root cause
Diagnostic CommandsCommands used for investigation
ResolutionFix steps
VerificationHow to confirm the issue is resolved

Issue: 502 Bad Gateway​

Symptoms​

  • Browser displays 502 Bad Gateway.
  • Nginx cannot reach the upstream service.
  • The application container or service may be stopped.

Diagnostic Commands​

docker ps
docker logs <container-name>
sudo nginx -t
sudo tail -f /var/log/nginx/error.log

Possible Causes​

  • Backend container is down.
  • Nginx upstream points to the wrong port.
  • Container is not attached to the expected Docker network.
  • Application service is running but unhealthy.

Resolution​

  1. Confirm containers are running.
  2. Check backend logs.
  3. Validate Nginx configuration.
  4. Confirm upstream host and port.
  5. Restart the affected service if required.

Verification​

curl -I https://example.com
curl https://example.com/health

Issue: 500 Internal Server Error​

Symptoms​

  • Browser or API returns 500 Internal Server Error.
  • Application logs show unhandled exceptions.

Diagnostic Commands​

tail -f storage/logs/laravel.log
php artisan about
php artisan config:clear
php artisan cache:clear

Possible Causes​

  • Invalid environment configuration.
  • Missing application key.
  • Database connection error.
  • Code exception.
  • Permission issue in storage or cache directories.

Resolution​

  1. Review the Laravel log.
  2. Check environment variables.
  3. Clear and rebuild Laravel caches.
  4. Confirm database connectivity.
  5. Fix the underlying application exception.

Verification​

curl -I https://example.com

Issue: Queue Workers Not Processing Jobs​

Symptoms​

  • Background jobs are delayed.
  • Notifications, exports, or scheduled actions are not processed.
  • Jobs remain in queue.

Diagnostic Commands​

php artisan queue:failed
php artisan queue:work
php artisan queue:restart

Possible Causes​

  • Queue worker is stopped.
  • Redis is not reachable.
  • Queue connection is misconfigured.
  • Failed jobs are accumulating.
  • Supervisor process is not running.

Resolution​

  1. Confirm queue driver configuration.
  2. Check Redis or database queue connectivity.
  3. Restart queue workers.
  4. Review failed jobs.
  5. Restart process manager if used.

Verification​

  • Submit a test background job.
  • Confirm it is processed.
  • Confirm no new failed jobs are created.

Issue: Redis Connection Error​

Symptoms​

  • Application cannot connect to Redis.
  • Queue, cache, or session operations fail.
  • Logs show Redis host or DNS resolution errors.

Diagnostic Commands​

docker ps
docker logs <redis-container>
docker network ls
docker network inspect <network-name>

Possible Causes​

  • Redis container is stopped.
  • Redis hostname is incorrect.
  • Application container is not on the same Docker network.
  • Redis port or credentials are misconfigured.

Resolution​

  1. Confirm Redis is running.
  2. Confirm the Redis host value.
  3. Confirm containers are on the same Docker network.
  4. Restart dependent application services.

Verification​

  • Confirm cache works.
  • Confirm queue workers process jobs.
  • Confirm logs no longer show Redis connection errors.

Issue: Database Connection Error​

Symptoms​

  • Application returns database-related errors.
  • Login or dashboard data loading fails.
  • Logs show connection refused, access denied, or unknown database.

Diagnostic Commands​

php artisan tinker
php artisan migrate:status
mysql -h <db-host> -u <db-user> -p

Possible Causes​

  • Incorrect database host.
  • Incorrect database username or password.
  • Database server is down.
  • Firewall or network restriction.
  • Missing database schema.

Resolution​

  1. Confirm database service is running.
  2. Confirm .env database values.
  3. Confirm user permissions.
  4. Confirm network access from the application server.
  5. Confirm migrations status.

Verification​

  • Login works.
  • Dashboard pages load data.
  • Logs show no new database connection errors.

Issue: Slow Dashboard or Reports​

Symptoms​

  • Dashboard pages load slowly.
  • Reports or exports take too long.
  • Database CPU or I/O usage is high.

Diagnostic Commands​

EXPLAIN SELECT * FROM orders WHERE student_id = 1;
top
htop
docker stats

Possible Causes​

  • Missing indexes.
  • Large table scans.
  • Heavy report queries.
  • Exports running during peak time.
  • Queue jobs competing with live traffic.

Resolution​

  1. Identify slow queries.
  2. Review indexes.
  3. Move heavy exports to background jobs.
  4. Schedule heavy reports outside peak hours.
  5. Add pagination or filtering where required.

Verification​

  • Page response time improves.
  • Database load decreases.
  • Reports complete within expected time.

Issue: Nginx Configuration Error​

Symptoms​

  • Site does not reload after Nginx changes.
  • Nginx reports invalid configuration.
  • Some routes return unexpected errors.

Diagnostic Commands​

sudo nginx -t
sudo systemctl status nginx
sudo tail -f /var/log/nginx/error.log

Possible Causes​

  • Invalid syntax in Nginx configuration.
  • Wrong upstream port.
  • Missing SSL certificate path.
  • Conflicting server blocks.

Resolution​

  1. Run sudo nginx -t.
  2. Fix the reported configuration line.
  3. Reload Nginx only after validation passes.
sudo systemctl reload nginx

Verification​

curl -I https://example.com

Issue: Login Failure​

Symptoms​

  • User cannot log in.
  • API returns unauthorized or validation error.
  • Authentication logs show failed attempts.

Diagnostic Commands​

tail -f storage/logs/laravel.log

Possible Causes​

  • Incorrect credentials.
  • Inactive user account.
  • Missing role or scope.
  • OTP provider issue.
  • Rate limiting or brute-force protection triggered.

Resolution​

  1. Confirm user account status.
  2. Confirm role and permission scope.
  3. Check OTP/SMS provider logs if applicable.
  4. Check rate-limit status.
  5. Reset access if approved.

Verification​

  • User can log in.
  • Correct dashboard permissions are applied.
  • Authentication log is recorded.

Issue Log Format​

When documenting a resolved issue, use this format:

## YYYY-MM-DD - Issue Title

| Field | Details |
|---|---|
| Environment | Production / Staging / Local |
| Impact | Low / Medium / High |
| Root Cause | Confirmed cause |
| Resolution | Fix applied |
| Verification | How it was confirmed |
| Owner | Responsible person/team |