Installation troubleshooting

Work from the symptom back to the failing component. Start with the pod status.

Check pod status

kubectl get pods -n zenintel
kubectl describe pod <failing-pod> -n zenintel
kubectl logs <failing-pod> -n zenintel --tail=200

Pods stuck in Pending

• No storage: confirm a default storage class exists and can provision volumes for PostgreSQL and RabbitMQ.
• Insufficient resources: check node CPU and memory against the requests in the manifests.

Pods in ImagePullBackOff

• The cluster cannot pull from ECR. Confirm the nodes have pull access to 337853574763.dkr.ecr.ap-southeast-3.amazonaws.com and that the image tag exists.

PostgreSQL never becomes ready

• Confirm the CloudNativePG operator is installed and running in cnpg-system.
• Check the cluster status: kubectl get cluster -n zenintel and kubectl describe cluster postgres -n zenintel.

Frontend will not load

• Confirm the frontend pods are Running and the ingress is routing.
• Confirm DNS resolves to the ingress and the TLS certificate is valid. See DNS and TLS.

Login fails

• Confirm the backend is healthy at /api/health and reachable.
• Confirm PostgreSQL is reachable (accounts live there).
• Confirm JWT_SECRET is present and consistent across backend replicas. A mismatched secret invalidates tokens.

AI actions never complete

• Confirm the ai-service pods are Running.
• Confirm LLM_API_KEY is set and correct, whether client-owned or Zentara Gateway.
• Check the ai-service logs for auth or timeout errors calling the LLM.
• If background jobs are stuck instead, check the ai-worker, asm-worker, and brand-worker pods.

Integration returns no data

• Confirm the integration is enabled and its key is set in the backend secret.
• For client-owned keys, check the provider account is active and within quota.
• For the Zentara Gateway, confirm the endpoint and token are correct and reachable from the cluster egress.

Database connectivity

• Confirm the DATABASE_URL password matches the zenintel-pg-app secret in data/postgres.yaml.
• Confirm the app points at the postgres-rw Service.

If an issue looks like a product defect, collect the diagnostics above and escalate. See the deployment guide for the support and escalation process.