Startup failed#

Self Hosted

When the web app cannot load what it needs, it shows a Startup failed dialog. The dialog lists the failed step, a short diagnosis, what to do next and the API address the page is using. This page explains each diagnosis.

Fix the cause, then use Check again or reload the page. Dismiss closes the dialog without fixing anything.

How the check works#

Check again looks at the failed request first, then asks the web server and the API:

  • GET /health on the address of the page. It only answers that the service is running and does not contact the database.

  • GET /api/system/health. It needs no key and returns databaseOk and redisOk.

curl http://localhost:8000/api/system/health

Replace the address with the one your page uses. A response such as {"status": "ok", "databaseOk": true, "redisOk": true} means the API can use both. The commands below assume the Docker compose install; use your own service names otherwise.

What each diagnosis means#

A failed request is shown with its method, path, status and request id. Include the request id when you search the logs or report a problem.

Diagnosis

What to check

Cannot reach the BrewGraph web server

The host is not running, or the address, port or HTTPS certificate is wrong. Run docker compose ps and docker compose logs brewgraph-web.

The request failed, but the web server answers now

The failure was probably temporary. Reload. If it returns, read the logs of brewgraph-web and brewgraph-api.

The browser blocked or could not reach the API address

The API address differs from the page address. Check VITE_APP_HOST or the proxy address, CORS, mixed content (an http API behind an https page) and the HTTPS certificate of that address.

The web server is up but the API is not answering

The answer was 502, 503, 504 or not JSON. Read docker compose logs brewgraph-api. The API may be restarting because the database is down.

The API is running but cannot use the database

/api/system/health reports databaseOk: false. Check that the database is up and reachable from the API service and that its schema is current. Read docker compose logs brewgraph-db and the API log.

The API hit an internal error

The answer was 500 with the database healthy. Search the API log for the request id shown in the dialog.

The API rejected the API key

The answer was 401. Make API_KEY the same for the web and API services and restart the web service so that env-config.js is generated again.

The page has no API key

env-config.js did not load or API_KEY is empty. Set API_KEY for the web service, restart it and reload the page without cache.

Too many failed attempts

The answer was 429. Wait the number of seconds shown, make API_KEY identical for both services and restart the web service.

The API refused the request

Any other status. Read the message in the dialog and the API log for the request id.

Startup failed for an unknown reason

No failed request was recorded. Reload. If it persists, check the browser console and the API log.

Redis#

redisOk: false means the API cannot reach Redis. Check that the Redis service is running and that the API service is configured with its address.