Troubleshooting

Useful checks when TaskBandit does not behave as expected.

Start with the health checks, then verify runtime config, proxy routing, certificates, and persistent data.

Quick health checks

Run these from the host running the Compose stack, replacing the example domains with your own public URLs.

docker ps
curl https://api.taskbandit.example.com/health
curl https://api.taskbandit.example.com/api/auth/providers
curl https://api.taskbandit.example.com/api/bootstrap/status
curl https://taskbandit.example.com/taskbandit-runtime-config.js

The API health endpoint should report a healthy server and database. The runtime config should show the public web and API base URLs your browser is expected to use.

Compose service names and logs

If docker compose logs taskbandit-server says there is no such service, your Compose project may still be valid but the service name might differ from the container name. Use container logs directly:

docker ps
docker logs --tail=100 taskbandit-server
docker logs --tail=100 taskbandit-web
docker logs --tail=100 taskbandit-postgres

For Compose-managed service names, inspect the file with:

docker compose config --services

Runtime config and env values

For a normal domain setup, these are the important public URL values:

TASKBANDIT_PUBLIC_WEB_BASE_URL=https://taskbandit.example.com
TASKBANDIT_PUBLIC_API_BASE_URL=https://api.taskbandit.example.com

The server derives the normal CORS origin from TASKBANDIT_PUBLIC_WEB_BASE_URL. You should not need legacy admin/client/CORS overrides unless you intentionally run an unusual deployment.

Check what the running containers actually received:

docker exec taskbandit-server env | grep TASKBANDIT_
docker exec taskbandit-web env | grep TASKBANDIT_

If the browser still loads stale values, recreate the web container and clear browser cache or test in a private window.

Cannot load setup or CORS errors

If the admin page says it could not load household setup, open browser developer tools and check the failing API request. Then test the same endpoint from the server:

curl -I -H "Origin: https://taskbandit.example.com" https://api.taskbandit.example.com/api/auth/providers
curl -I -H "Origin: https://taskbandit.example.com" https://api.taskbandit.example.com/api/bootstrap/status

Expected result: successful responses should include an allowed origin for the web URL. If they do not, verify the running server has the correct TASKBANDIT_PUBLIC_WEB_BASE_URL and TASKBANDIT_PUBLIC_API_BASE_URL, then recreate the stack.

Certificate and proxy checks

If the API works by IP but fails by HTTPS domain, check the certificate served by the proxy:

openssl s_client -connect api.taskbandit.example.com:443 -servername api.taskbandit.example.com </dev/null | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

For Nginx Proxy Manager, the SSL tab should normally have a valid certificate selected for the domain, Force SSL enabled, HTTP/2 support enabled if available, and Websockets Support enabled on the proxy host. Keep the API host forwarding to port 8080 and the web host forwarding to port 4173 on the Docker host, or to container ports if NPM shares the Docker network.

403 from the admin path

The admin UI lives under the same web host as the client UI. Do not create a separate proxy host for /admin. Use:

https://taskbandit.example.com/        -> taskbandit-web
https://taskbandit.example.com/admin/ -> taskbandit-web
https://api.taskbandit.example.com/   -> taskbandit-server

If /admin redirects to an IP URL or drops the expected port, check the proxy host target and the runtime config file.

Reset for testing

To reset a test install while keeping your Compose and env files, stop the stack and move the persistent data folder aside:

cd ~/taskbandit
docker compose down
mv data "data-reset-$(date +%Y%m%d-%H%M%S)"
mkdir -p data/postgres data/taskbandit
docker compose pull
docker compose up -d --force-recreate

Then clear browser site data for the TaskBandit domain, or use a private window, so an old token does not point at a fresh database.

Demo data

Demo seed data is off by default. Use it only for testing or walkthroughs:

TASKBANDIT_BOOTSTRAP_SEED_DEMO_DATA=true

For normal installs, keep it false and use the first-household setup flow instead.