Logs & Troubleshooting

Diagnose a running installation from container logs and health endpoints. This guide follows version 3.1.7 (03acdf712c).

For startup from source, see Local Setup. For background workers, see Background Services.

Health checks

curl --fail http://localhost:3300/health
curl --fail http://localhost:4000/health
curl --fail http://localhost:4000/graphql \
  -H 'Content-Type: application/json' \
  --data '{"query":"query Health { __typename }"}'

Core API and gateway should return ok. The GraphQL query must return data.__typename === "Query". Gateway ok alone does not prove Apollo Router composition finished; inspect the gateway logs for service registration and supergraph compose errors.

Where to look

• docker compose ps and docker compose logs core-api gateway core-ui logs-service redis for service status.
• Gateway logs for retryGetProxyTargets, missing erxes-service-<name> Redis keys, unreachable <address>/graphql, and Router download failures.
• Plugin API logs for startPlugin, Mongo/Redis connection errors, and permission or tenant (subdomain) failures.
• Browser Network panel and console for /get-frontend-plugins, remoteEntry.js, and GraphQL errors arrays. HTTP 200 with a GraphQL errors array is not success.

Common causes

• MongoDB/Redis unreachable: match MONGO_URL, REDIS_HOST, REDIS_PORT, and Docker networking. From containers, use service names; from the host dev setup, use 127.0.0.1.
• Gateway waits for a plugin: check ENABLED_PLUGINS spelling (no spaces, no _api suffix), that the API container is running, and that its registered address is reachable.
• Plugin UI missing: confirm the plugin image or remote is deployed and that production remoteEntry.js URLs under plugins.erxes.io (or your asset host) are reachable. See Deployment.
• Widget connects to localhost: the widget build baked REACT_APP_API_URL; rebuild with the public gateway URL. See Messenger Installation.
• Out of memory in development: run fewer plugins or raise NODE_OPTIONS=--max-old-space-size=4096 per Node process.

Source references

• Gateway proxy targets.
• Router startup.
• Plugin discovery.