Troubleshooting

Collabase reports errors before they cause data issues. Here is how to diagnose and resolve the most common problems.

Connection lost overlay

If you see a black “Connection Lost” screen:

Check if the database container is running

docker ps

Look for the db container in the output. If it is not listed or shows Exited, the container has stopped.

Check database logs

docker compose logs db

Look for any startup errors or disk-full messages.

Verify the DATABASE_URL

Open your .env file and confirm that DATABASE_URL points to the correct host, port, and database name.

To see what the application is doing in real time:

docker compose logs -f app

Collabase exposes a built-in health endpoint used by Docker’s health check. You can call it manually to confirm the system state:

curl http://localhost:3000/api/health

Response	Meaning
`200 OK`	The system is `READY` and healthy
`503 Service Unavailable`	The system is in a setup or update state — normal during first run or migration

Action	Command
Restart all containers	`docker compose restart`
Hard reset (keep data)	`docker compose down && docker compose up -d`
View running containers	`docker ps`
Rebuild image (rarely needed)	`docker compose up -d --build`

If uploads fail or the application cannot write files:

Check folder permissions

Confirm that collabase_data and shared-home on the host are writable by the user running Docker.

Re-run the migration script

./migrate-data.sh

This script resets the correct ownership and permissions on all data folders.