Database connection and “Japella is not ready”

If the web interface shows Japella is not ready, the browser reached the Control API but GetStatus reported that the database is not connected. If the UI shows Could not reach the Japella server instead, see server unreachable troubleshooting — the API call itself failed before Japella could report database health.

Older builds may have shown “translations could not be loaded” for some of these cases; current versions check server status before loading translations.

Quick checks

  1. Database running — Ensure MariaDB or MySQL is up and accepting connections on the host and port configured for Japella.

  2. Configuration — Verify database host, name, user, and password in config.yaml (or the equivalent environment variables such as JAPELLA_DB_HOST, JAPELLA_DB_USER, JAPELLA_DB_PASS, JAPELLA_DB_NAME).

  3. Network — From the Japella container or host, confirm the database hostname resolves and the port is reachable (firewalls, Docker network names, and depends_on only affect startup order, not guaranteed readiness).

Docker Compose

When using Compose, define a database service and point Japella at it. See Docker Compose installation for a full example, including a MariaDB service and JAPELLA_DB_* environment variables.

Inspect logs if the UI stays in an error state:

  • docker compose logs japella

  • docker compose logs mariadb (or your database service name)

Standalone or custom installs

For non-Compose setups, follow standalone installation and ensure the database exists, credentials match, and Japella can run its migrations on first successful connection (check Japella logs if the schema does not update).

Configuration reference

Database-related settings are described alongside other options in Configuration.