Common issues
The following table details common issues encountered during installation and their likely resolutions.
| Symptom | Likely cause | Fix |
|---|---|---|
DNS_PROBE_FINISHED_NXDOMAIN in browser | The domain in your values file does not match your cluster’s wildcard DNS routing. | On OpenShift/ARO, ensure domain is a subdomain of apps.<cluster> (e.g., dataqi.apps.<cluster>), not apps.<cluster> itself. |
API pod CrashLoopBackOff with FormatException: Connection string not in expected format | The NATS password is empty or missing. | Ensure you have properly provisioned the dataqi-nats-auth and dataqi-nats-connection secrets as per the Secrets management guide. |
The parquet-query-worker container repeatedly restarts | Its liveness command is failing, the worker exceeded its resource limit, or pod ephemeral storage is exhausted. | Inspect kubectl describe pod and the worker container’s previous logs. Confirm the node and pod have enough memory and ephemeral storage, then review apps.api.parquetQuery limits. Query errors alone do not fail worker liveness. |
Pods stuck in Pending with binding volumes: context deadline exceeded | The configured storage class is missing or does not support ReadWriteMany (RWX) volumes. | Create an RWX-capable storage class and ensure it matches the storageClass.shared value in your configuration. |
CloudNativePG (CNPG) operator pods show Forbidden | Missing SecurityContextConstraints on OpenShift. | Apply the cnpg-scc.yaml manifest before installing the chart. |
nats pod fails with cd: can't cd to /root: Permission denied | The OpenShift restricted-v2 SCC blocks the /root home directory. | Ensure HOME=/tmp is set in the NATS container.merge environment block in your values file. |
| Cryptographic error in API pod logs during startup | The Data Protection certificate is missing or invalid. | Ensure you provisioned the dataqi-api-data-protection secret from the binary PFX file, not from a Base64 string. |
/docs/ returns the SPA or a 404 after deployment | The running SPA image predates bundled documentation, or the SPA route is not reaching its Nginx container. | Confirm the deployed SPA image version, then verify that the existing SPA route forwards /docs/ without a path rewrite. No separate documentation service or Helm value is required. |