Skip to content

Troubleshooting

Start with the route and the layer that failed. Do not change Nginx when the application returned a valid error.

Scenario templates are missing

Check these layers in order:

  1. Open /themis/health.
  2. Check GET /themis/v1/scenarios.
  3. Check the API container logs.
  4. Confirm that data/scenarios.yaml exists in the container image or mounted project directory.
  5. Confirm that the browser received JSON instead of an HTML error page.

The browser should show a clear empty state. It should not silently replace a missing catalog with a fake release result.

A run returns to NOT RUN

The UI must keep RUNNING until the final response arrives.

Check:

  • browser network errors;
  • the final API response status;
  • the response release ID;
  • the container logs during the run;
  • whether the browser loaded a stale HTML or JavaScript bundle.

Clear the browser cache only after checking the deployed asset version.

The docs path returns 404

Check:

  1. build/docs-site/index.html exists locally.
  2. The VPS directory contains index.html and search/.
  3. The Nginx alias ends with /.
  4. /themis/docs redirects to /themis/docs/.
  5. nginx -t passes.
  6. Nginx was reloaded after the new config was installed.

The docs page is blank or has no styles

Check the browser network panel for /themis/docs/assets/ and /themis/docs/stylesheets/extra.css. The MkDocs site_url must include the full /themis/docs/ prefix. Build paths must not point to /assets/ at the domain root.

DataHub evidence is missing

Read the receipt state. UNAVAILABLE, NOT_CONFIGURED, and ERROR are different states. Check the DataHub GMS URL, MCP service, token environment, and Docker network. Do not label the run PROMOTE because SQL alone passed.

OpenTelemetry values are missing

Check the collector endpoint, Jaeger service, and the optional Jaeger test. The Analytics Agent cannot answer a live trace query unless a telemetry query connector is configured. Use the Themis receipt for the trace IDs that the run actually returned.

Apollo looks different after a deployment

Stop the deployment and compare the active Nginx configuration with the last known good backup outside sites-enabled. Check the Apollo container before changing any shared service. A docs-only deployment should not recreate Apollo or the shared DataHub stack.