Troubleshooting
Container Won't Start
docker compose logs megadexAt boot Megadex validates its environment (DB_JOB_USER and DB_JOB_PWD are required). Database connections are opened lazily, so a missing DB_HOST or DB_PWD shows up at the first query or readiness check. The migration container not having finished is another usual cause. Check that megadex_migration exited successfully before the service tried to start.
Megadex Is Reachable Directly
Treat this as a deployment error. Megadex relies on a BFF for authentication and ACL headers (x-consumer-*, x-acl-*) and must not have a public Traefik API router, published host port, or public load-balancer target on port 3000. Only the bundled Admin UI port (ADMIN_PORT, e.g. 8080) should be routed by Traefik.
Database Connection Issues
# Check if PostgreSQL is running
docker exec my-project-postgres-local pg_isready -U root -d megadex
# Test connection from the Megadex container
docker exec my-project-megadex-local nc -zv my-project-postgres-local 5432
# Readiness endpoint proves the app itself can query
docker exec my-project-megadex-local wget -qO- http://localhost:3000/megadex/health/readyIf /megadex/health answers but /megadex/health/ready fails with 503, the process is alive but has lost the database — the readiness probe is taking the instance out of rotation.
Migration Failures
# View migration logs
docker logs my-project-megadex-migration-local
# Roll back the last two changesets
docker compose run --rm -e UPDATE=0 -e ROLLBACK=2 megadex_migrationThe migration entrypoint enters rollback mode only when ROLLBACK is greater than 1; ROLLBACK=1 falls through to diff mode.
User Creation Fails and Archives the New Row
When PWD_CREATE_URL is set, POST /megadex/users calls the password service's create endpoint right after inserting the user row. If the password service is unreachable or returns an error, Megadex soft-archives (active = false, archived = true) the newly created user so an account without credentials cannot be left active.
Check that the password service is healthy on the internal network and that PWD_CREATE_URL points to http://<password-service-host>:3000/pwd.
403 When Creating, Updating, or Archiving a User
Two guards can reject user mutations with 403 Forbidden:
- Super-admin role ceiling (
assertSuperAdminCeiling) — Only a caller who holds role1(Super admin) inuser_rolecan assign role1to a user or modify/archive an existing user who holds role1. Standard administrators (role2) receive403 Cannot assign super admin roleor403 Cannot modify or archive a super admin user. - ACL field or condition restrictions (
x-acl-fields,x-acl-conditions) — If the caller's BFF permission restricts writable fields or row conditions, attempting to write a disallowed field or target a row outside the partition returns403.
403 on PUT /megadex/users/me
The self-service endpoint PUT /megadex/users/me intentionally blocks privilege-escalation and identity-anchor fields:
roles/rolesArrayAggactivearchivedemail
Including any of these keys in a PUT /megadex/users/me payload returns 403 Field "<field>" cannot be modified via /me. Omit them from self-service profile forms and use the administrative PUT /megadex/users route for role, status, or email changes.
Unknown or Archived Social Network Error
When socialsJsonAgg is sent on POST /megadex/users, PUT /megadex/users, or PUT /megadex/users/me, the PostgreSQL function set_user_socials() resolves each key against non-archived rows in the social table. If a key does not match an active social network name, the database raises an exception.
Check the active catalog with POST /megadex/socials/search (filtering archived = false) or add the missing platform via POST /megadex/socials.
Role Changes Do Not Take Effect Immediately
Megadex does not revoke BFF sessions when an administrator updates a user's roles, sets active: false, or archives the account. Existing sessions remain usable until the access token expires; archived or inactive accounts cannot refresh their sessions.