Troubleshooting
These instructions are for Manifold v9 and later. If you are running Manifold v8 or earlier, see the legacy troubleshooting instructions.
Logging
When Manifold isn't working the way it should, the best place to begin troubleshooting is by looking at container logs. In a v9 deployment, each service runs in its own Docker container, and you can tail logs using the deploy CLI or Kamal directly.
Tailing Container Logs
Use the deploy CLI to tail logs for a specific service:
bin/deploy logs -d production api
bin/deploy logs -d production client
bin/deploy logs -d production worker
Or use Kamal's built-in aliases:
kamal logs-api -d production
kamal logs-client -d production
kamal logs-worker -d production
To view database logs (local database only):
kamal accessory logs db -d production
Diagnosing Errors
If you're encountering an application error, start by figuring out if it's a client error or an API error. If you're seeing a 500 error from the API, it could indicate a misconfiguration or a bug. Check the API logs to better understand what's causing the error. Errors in the client application will show up in the client logs, or in your browser's developer tools console. If you see errors in these places, please report them to us on Slack. If there's a bug in Manifold, we want to know about it!
Checking Container Status
If a service isn't responding, verify that all containers are running:
bin/deploy status -d production
For more detail on specific containers:
kamal app details -d production
kamal accessory details client -d production
Background Jobs
Manifold runs a number of tasks in the background, including but not limited to image processing, email delivery, collection membership calculations, epub generation, and project packaging. Starting with v9, Manifold uses GoodJob to manage these job queues. GoodJob stores jobs directly in the PostgreSQL database, which eliminates the need for a separate Redis service.
GoodJob includes a built-in web dashboard for monitoring job queues. If you are logged in to your Manifold instance as
an admin user, you can access it at https://your-domain/api/good_job. The dashboard shows running, queued, failed,
and completed jobs, and is a good first stop when investigating background job issues.
The worker container processes background jobs. If jobs appear to be stuck or failing, check the worker logs:
bin/deploy logs -d production worker
Common Issues
/api requests return 502 or 404 — the API container may not be running or healthy. Check its status and logs:
kamal app details -d production
bin/deploy logs -d production api
SSL certificate not issued — ensure your domain's DNS A record points to the server IP and that ports 80 and 443 are open. Let's Encrypt needs to reach the server to issue certificates.
Client can't reach the API — all containers must be on the kamal Docker network. Verify with:
bin/deploy remote -d production "docker network inspect kamal"
Database connection refused — for a local database, the container may not be ready yet. Check its status and logs:
kamal accessory details db -d production
kamal accessory logs db -d production
For an external database, verify the host, port, credentials, and that the managed cluster allows connections from your server's IP.
Assets return 404 — with local storage, ensure the uploads volume is mounted. With MinIO, check that the storage
accessory is running. With external S3, verify your S3_ENDPOINT, UPLOAD_BUCKET, and S3_REGION values in your
destination configuration file.
Memory Consumption
Like many Ruby applications, the Manifold API can consume and hold onto available memory. If Manifold is non-responsive or unstable, monitor the available memory on your server and consider increasing the resources devoted to Manifold. You can check resource usage with:
bin/deploy remote -d production "docker stats --no-stream"
More Information
For additional troubleshooting guidance, see the README in the deploy template repository.