CMS Troubleshooting

Start with the exact error, its time, and the last configuration change. Check application logs and the service manager's output. Keep the database intact while investigating.

Application does not start

Check that:

• You are using the runtime required by the release.
• Production dependencies installed successfully.
• The start command points to the actual bin/server.js.
• The application is reading the intended environment file or platform settings.
• DATABASE_URL uses PostgreSQL and is reachable from the application host.
• The application user can access the release and persistent storage.

A bootstrap error about resolving APP_KEY from the database can indicate bad credentials, connectivity, or insufficient permissions to access the runtime-secret table. Fix the database connection rather than generating a different application key repeatedly.

A missing generated Prisma JavaScript file can result from running prisma generate on a precompiled release. Restore the compiled client from the matching clean release; do not mix generated files from another version.

Proxy shows a gateway error

Confirm the service is running and listening on the port configured in the proxy. Check HOST: loopback is suitable for a local proxy, but a container ingress may require 0.0.0.0.

Use /api/health to check HTTP reachability. If it responds but the application is still unhealthy, inspect database and module checks in System Health and the logs. The health endpoint itself does not validate the database.

Installer reappears or stops partway

Confirm that the app is using the same database as before. An accidental change to the connection string can look like a new installation.

For a partial first install, capture the wizard error and migration logs. Review what completed and use the appropriate remaining step. Do not drop the database or run a production reset to make the wizard start over.

License is rejected

Symptom	Check
Key invalid or missing	Copy the issued key from the correct portal service
License pending, suspended, or expired	Review payment, service state, and due dates with support
Domain mismatch	Use the final public hostname and check whether reissue is required
IP mismatch	Check the server's outbound/public IP and any changed NAT or proxy
Directory mismatch	Compare the current working directory with the bound directory
Remote check fails	Check DNS resolution, outbound HTTPS, certificates, and server time
Response signature fails	Verify the release is genuine and contact support; do not disable signature verification
Paid module absent	Check the service entitlements and subsequent successful CMS license validation

See licenses and downloads. Cached validation is conditional; it does not permit a new installation to activate while the issuer is unreachable.

Sign-in does not persist

Production sessions use secure cookies. Access the public site over HTTPS, confirm the proxy preserves the correct host and scheme, and make sure APP_KEY remains stable across processes and restarts.

For a restored database, retain its runtime-secret table and any explicit key configured for the original installation. Unintentionally overriding the key can invalidate existing sessions.

Email links point to localhost

Set APP_URL to the canonical HTTPS origin and restart the application. Send a fresh test message. The company website setting and INSTALL_PUBLIC_URL do not replace this runtime value.

If no mail arrives, inspect the selected communication provider, credentials, sender verification, cloud wallet where applicable, and delivery results.

Real-time updates work in only one browser

Check the browser's WebSocket connection to /socket.io, proxy upgrade forwarding, and the allowed origin derived from APP_URL.

If users on different processes do not receive updates, configure REDIS_URL and confirm all processes can connect. The internal cluster adapter only connects workers managed by the same application primary; it is not a bridge between independent hosts or Passenger processes.

Uploads disappear after deployment

Check the resolved APP_ROOT and whether storage/uploads is on persistent storage. Verify the same path is used before and after deployment. A changed path can make intact uploads appear missing.

For multiple replicas, check shared storage or the external upload provider. A file written to one replica's local disk is not automatically present on another.

Module fails to load

Look for missing compiled files, manifest errors, or failed module migrations in startup output. Confirm that the complete module directory shipped with the release, dependencies are present, and license entitlement is correct.

Do not mix source TypeScript modules with compiled production modules as an improvised fix. Restore the matching complete release and approved extensions, then restart and inspect the result.

Escalate with evidence

Use the support checklist and include the release version, deployment type, failed step, exact error, and recent changes. Remove secrets from the evidence before sending it.