Skip to main content

Troubleshooting

Start in your installation directory with docker compose ps and docker compose logs --since=10m api web worker cron ws db cache search. Include your original optional overlay arguments in all commands. There is no docs or private console container. Review logs privately and redact secrets/customer data before sharing excerpts.

502 or unavailable API​

Check https://api.yourdomain.com/api/health, API health, migrations and api logs. For Caddy, inspect proxy logs, DNS and host port ownership. For Tunnel, inspect cloudflared logs, its connection status and service targets. Internal targets are api:4000, web:4001, ws:8083—not host-local published ports.

Database authentication or missing tables​

Confirm DB_HOST=db, stored MySQL username/password and database health. MySQL initialization variables only create users on a new volume; editing .env does not reset stored credentials. Do not delete volumes to fix authentication. Review migration logs; initial core seeding is separate from routine migrations.

Cannot sign in as the business owner​

The revised public image does not create a tenant from INITIAL_ADMIN_* settings. Register an owner through the ERP, verify email and complete onboarding. A technical system administrator from an older installation is not a business owner and has no workspace merely because the account exists. Do not repeatedly seed to reset it. Confirm SMTP/queue operation if verification mail is missing.

Wrong frontend configuration​

Check that web/.env.frontend exists. Both API variables use the public API origin without /api. Recreate web after changing values. The public image rejects attempts to enable SaaS billing or cloud deployment flags; use the self-hosted settings. A NuSaaS subscription or hosted-WhatsApp checkout is not part of this distribution.

CORS and WebSockets​

Match backend CORS to the exact frontend HTTPS origin. Match browser and backend Reverb keys. Guided Caddy uses the API hostname and forwards /app/* to Reverb; a dedicated WebSocket hostname must forward to ws:8083. Browser port is 443 with wss. Check trusted proxies and WebSocket forwarding, then recreate affected containers rather than only restarting.

Missing logos or documents​

Confirm storage-data is mounted and Laravel's public/storage link is recreated by the bootstrap. If using R2, check the configured disk, bucket credentials and object delivery path; changing the storage disk does not migrate existing files. Recover matching file backups rather than resetting the database.

WhatsApp will not verify or reply​

Confirm the gateway is enabled, the approved HTTPS origin matches exactly, its public DNS resolves safely, and the credential is scoped to the correct instance. Private/HTTP destinations are intentionally rejected. Check that callbacks reach the public API without a browser challenge and contain the generated authentication header. Send a fresh verification code from another number before activation.

A linked phone, gateway acceptance and final delivery are separate evidence. Inspect the recorded state and sending-budget waits; do not replay unknown outcomes blindly. Do not fix pairing by deleting session/database volumes. See WhatsApp setup.

Installer assets or image tag unavailable​

Do not continue a partial installation. Confirm the selected release actually published both images and matching installer files. The revised distribution has a pending-release notice until verification/publication is complete. Do not substitute cloud builds, latest, private repository clones or random third-party images.