Troubleshooting

Troubleshooting

Each issue below is listed as Symptom → Likely cause → Fix. ForgeChat's containers are forgecrm-backend, forgecrm-frontend, forgecrm-db, and redis. Check logs with:

docker compose logs -f forgecrm-backend

A container won't start

• Symptom: a service keeps restarting or exits immediately.
• Likely cause: a missing or invalid setting in backend/.env (in production the backend refuses to start without a valid JWT_SECRET and FORGECRM_ENCRYPTION_KEY), or the build ran out of memory.
• Fix: check docker compose logs forgecrm-backend. Ensure JWT_SECRET and FORGECRM_ENCRYPTION_KEY are set to random values of at least 32 characters. If the build was "Killed" / out of memory, use 2 GB+ RAM or add swap, then rebuild.

Can't connect to the database or Redis

• Symptom: backend logs show connection errors to Postgres or Redis.
• Likely cause: the database/cache isn't ready yet, or DATABASE_URL / REDIS_URL don't match the compose service names.
• Fix: start them first and wait for health: docker compose up -d forgecrm-db redis. Confirm DATABASE_URL points at host forgecrm-db and REDIS_URL at redis, and that POSTGRES_PASSWORD matches the password inside DATABASE_URL.

Dashboard loads, but messages won't send

• Symptom: the UI works, but outgoing messages fail.
• Likely cause: WhatsApp isn't connected, the access token is invalid, or you're outside the 24-hour reply window.
• Fix: confirm your number under Settings → WhatsApp Accounts (valid Phone Number ID, WABA ID, and a permanent access token). To message outside the 24-hour window, send an approved template. See WhatsApp Business API / Meta Setup.

Webhook not receiving inbound messages

• Symptom: messages sent to your business number never appear in Chats.
• Likely cause: the Meta webhook is misconfigured.
• Fix: in the Meta dashboard, verify the Callback URL ends with /api/webhook/whatsapp, the Verify token exactly matches META_WEBHOOK_VERIFY_TOKEN (no extra spaces), and you've subscribed to messages. The Callback URL must be public HTTPS. Test with Settings → Webhooks → Send Test Webhook.

A template was rejected by Meta

• Symptom: a template shows Rejected.
• Likely cause: the content breaches Meta's template rules (e.g. promotional content in a Utility template, variable/sample issues, or formatting).
• Fix: read the rejection reason shown on the template, revise the wording or category, and resubmit. Approval is decided by Meta — see Template Builder.

Changed .env but nothing updated

• Symptom: new settings don't take effect.
• Fix: restart the backend so it re-reads the file: docker compose restart forgecrm-backend.

---

See also: Installation • WhatsApp Business API / Meta Setup • FAQ