Shrey Gupta
11/07/2025, 12:25 AMkapa.ai
11/07/2025, 12:26 AMairbyte-db service. ## Root Cause The issue is typically that the airbyte-db pod is not ready or running when the bootloader tries to connect to it. According to the [troubleshooting documentation](https://docs.airbyte.com/platform/deploying-airbyte/troubleshoot-deploy), "Failures reasons are generally related to problem of airbyte-bootloader not able to connect to the airbyte-db service." ## Common Scenarios From the knowledge sources, several scenarios can cause this: 1. Database pod not starting: The airbyte-db pod may be in a Pending state due to volume provisioning issues. In [one case](https://discuss.airbyte.io/t/3127), the database pods were pending because persistent volumes were waiting to be created by the external provisioner. 2. Database initialization issues: The database container may be failing to start due to permission issues or initialization errors, as seen in [this issue](https://github.com/airbytehq/airbyte/issues/54199) where PostgreSQL had invalid directory permissions. 3. Connection refused: The database service may not be accepting connections yet, as shown in [this GitHub issue](https://github.com/airbytehq/airbyte/issues/68136) with Connection refused errors. ## Troubleshooting Steps To diagnose your specific issue, check: 1. Pod status: Run kubectl get pods -n <your-namespace> to see if the airbyte-db pod is running 2. Pod events: Run kubectl describe pod <airbyte-db-pod-name> -n <your-namespace> to check for errors 3. Database logs: Run kubectl logs <airbyte-db-pod-name> -n <your-namespace> to see if there are initialization errors The airbyte-db-svc service should indeed be created automatically as part of the Helm deployment. If the service exists but the pod isn't running, that's where your issue lies. The bootloader is designed to wait for the database to become available, but it will eventually timeout (as you're experiencing) if the database never starts successfully.Shrey Gupta
11/07/2025, 12:28 AMkapa.ai
11/07/2025, 12:29 AMkapa.ai
11/07/2025, 12:29 AMairbyte-db pod is not appearing in your namespace, here are the steps to diagnose and fix the issue: ## Check for Volume Provisioning Issues The most common reason for database pods not appearing is persistent volume provisioning problems. According to [this forum post](https://discuss.airbyte.io/t/3127), you should check: bash kubectl -n <your-namespace> get events --sort-by='{.lastTimestamp}' Look for messages like: - waiting for first consumer to be created before binding - waiting for a volume to be created, either by external provisioner ## Verify StatefulSet Status Check if the StatefulSet for the database was created: bash kubectl get statefulsets -n <your-namespace> If you see airbyte-db-0 in a Pending state, check the persistent volume claims: bash kubectl get pvc -n <your-namespace> ## Common Fixes 1. Storage Class Issues: According to [this GitHub issue](https://github.com/airbytehq/airbyte/issues/61497), ensure your Kubernetes cluster has a default storage class configured or specify one in your Helm values: yaml postgresql: persistence: storageClass: "your-storage-class" 2. Resource Constraints: From [this forum discussion](https://discuss.airbyte.io/t/3825), ensure your nodes have sufficient resources. The issue was resolved when proper storage provisioning was configured. 3. Check Helm Status: Run: bash helm status airbyte -n <your-namespace> kubectl describe statefulset airbyte-db -n <your-namespace> If the StatefulSet itself wasn't created, there may be an issue with your Helm values or chart version. The knowledge sources suggest verifying your Helm chart version is compatible with your Kubernetes version.