Troubleshooting & Incident Recovery
Diagnostic commands, password recovery, encrypted backup restoration, and fixes for common self-hosted runtime issues.
Essential Diagnostic Commands
# 1. Check container runtime status and port bindings
docker compose ps
# 2. View live application logs (last 100 lines)
docker logs --tail 100 -f eventwrappro-app
# 3. View database container logs
docker logs --tail 100 -f eventwrappro-db
# 4. Test internal health endpoint
curl -s http://127.0.0.1:3000/api/health
# 5. Check disk space availability
df -hIncident Runbooks
Admin Password Reset (UI, Email Fallback, or CLI Helper)
Root Cause: Administrator credentials lost or locked out without an active SMTP server configured.
- If another Admin is signed in: reset the user password from Admin -> Settings -> Users.
- If SMTP is unconfigured and you have host shell access, run the CLI emergency reset inside the running container:
docker exec -it eventwrappro-app node scripts/reset-admin-password.mjs [email protected] NewSecurePassword123!
Disaster Recovery from .ewpbak Host Backup
Root Cause: Migrating to a new server or recovering from host disk failure with existing /app/backups/*.ewpbak files.
- Place your .ewpbak archive inside ./backups on the new host (owned by uid 1001:1001).
- On a fresh install, /setup Step 1 automatically detects Host Backups and lets you unlock & restore with your Slot A key (EWP-REC-XXXX-XXXX-XXXX-XXXX) or Slot B BACKUP_ENCRYPTION_KEY.
- On an existing install, upload and restore directly from Admin -> Settings -> Backups -> Restore.
PrismaClientInitializationError: Can't reach database server at db:5432
Root Cause: The PostgreSQL container is not running, exited, or DATABASE_URL credentials do not match POSTGRES_PASSWORD.
- Run 'docker compose ps' to check if 'eventwrappro-db' is healthy.
- Check database error logs: 'docker logs eventwrappro-db'.
- Verify DATABASE_URL in .env matches POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB.
- Restart the stack: 'docker compose restart'.
502 Bad Gateway or Upstream Connection Refused
Root Cause: Your reverse proxy (Nginx, Caddy, Traefik) cannot reach port 3000 on localhost.
- Verify the app container is running: 'docker compose ps'.
- Test local HTTP response from the server shell: 'curl -I http://127.0.0.1:3000/api/health'.
- Inspect application logs for boot errors: 'docker logs eventwrappro-app'.
Artwork Upload Fails with 413 Payload Too Large or EACCES
Root Cause: Nginx defaults to a 1 MB upload limit, or ./uploads / ./data / ./backups are not owned by uid 1001 (nextjs).
- In Nginx, set 'client_max_body_size 110M;' and reload.
- Fix host directory ownership: 'sudo chown -R 1001:1001 uploads data backups'.
Geo-Mismatch Security Alert or Unexpected Login Block
Root Cause: A user logged in from a new country or VPN IP compared to lastLoginCountry (detected via CF-Connecting-IP), or Cloudflare Turnstile keys are misconfigured.
- Review recent authentication events under Admin -> Settings -> Logs (Authentication tab).
- Verify NEXTAUTH_URL / AUTH_URL matches your exact HTTPS domain for Passkeys and Turnstile.
License Ping Warning: Offline Grace Period Active
Root Cause: Temporary interruption reaching https://eventwrappro.com/api/license/ping. The 14-day autonomous offline grace window keeps shop operations running.
- Verify outbound HTTPS connectivity from the host: 'curl -I https://eventwrappro.com'.
- Ensure LICENSE_KEY in .env matches your active subscription and click Re-Sync under Settings -> License.