Skip to content
ArtificialFlow

Troubleshooting

Start with the rendered config, then identity, then the connector. A healthy pod only means the process started.

Compose does not become ready

docker compose -f artificialflow.compose.yml config --quiet
docker compose -f artificialflow.compose.yml ps
docker compose -f artificialflow.compose.yml logs
  • The generated file needs Compose v2.23 or newer because the gateway config is embedded with configs.content.
  • Elasticsearch needs memory and a few minutes on first boot. A short timeout on the first health check is expected.
  • If the command API is up and the connector is missing, run make init-connector from a checkout of the product repository as a recovery step.
  • External login failures usually mean the redirect URI, audience, or roles claim does not match the file. Compare the issuer URLs with IAM and roles.
  • Empty databases after a restart usually mean Compose attached a new project or volume. Fresh files use project artificialflow and the artificialflow-* volume names. Reattach the names that already exist, and leave volume-deleting cleanup out of that recovery.

Cannot log in

  • The frontend runtime config must point at the issuer the browser can open.
  • Command and query must use the internal issuer they can reach and the public issuer printed in tokens.
  • The browser client id must match the client registered at the provider.
  • In production, AUTH_ENFORCE_AUDIENCE=true must match the audience on issued tokens.

Query results are empty

Command or query health of ok with an empty catalog usually means projection has not caught up. Confirm the sync worker is healthy, Kafka is reachable, Debezium topics have consumers, and Elasticsearch answers. From a product checkout:

make cqrs-e2e-smoke

SDK calls are unauthorized

  • The machine client must be active and hold only artificialflow client.
  • The token must include the backend audience and the role claim. The role claim path must match AUTH_CLAIM_ROLES_PATH.
  • In JWT mode the token issuer matches AUTH_ISSUER_PUBLIC_URL. In introspection mode the endpoint returns active=true, a subject, the expected audience, and the role claims.
  • Clocks on the caller and the issuer need to agree, or a short-lived token is already expired.

Helm install fails

helm lint ./charts/artificialflow -f ./artificialflow-values.yaml
helm template artificialflow ./charts/artificialflow -f ./artificialflow-values.yaml
  • The values file uses iam.mode=external when Integrate with IAM is true, or iam.mode=disabled when it is false, plus search.backend=elasticsearch and eventBus.type=kafka.
  • When postgresql.existingSecret is set, that Secret must contain PG_DSN. In introspection mode it must also contain AUTH_INTROSPECTION_CLIENT_SECRET.
  • Image repositories and tags must be pullable by the cluster.
  • Kafka brokers and the Debezium Connect URL must be reachable from the sync worker.
  • An older release that must keep its current names sets compatibility.legacyResourceNames from the live fullname and selectors. A fresh install leaves that block disabled.

The deployment guide's postconditions are the definition of done.