Troubleshoot

​

Database never becomes Ready

​

Symptom

kubectl wait --for=condition=Ready cwdbcluster [CLUSTER-NAME] \
  --namespace [NAMESPACE] \
  --timeout=300s

​

What to check

1. Inspect the database status:
   kubectl describe cwdbcluster [CLUSTER-NAME] --namespace [NAMESPACE]
   
   Look at the Status.Conditions section. The condition messages typically point at the underlying problem (scheduling, storage, image pull, certificate generation).
2. Check the pods:
   kubectl get pods --namespace [NAMESPACE] -l cnpg.io/cluster=[CLUSTER-NAME]
   
   A pod in Pending state usually means the scheduler can’t place it. kubectl describe pod on that pod surfaces the reason, most often “no CPU nodes available” or “Insufficient memory”.
3. Check the PersistentVolumeClaims (PVCs):
   kubectl get pvc --namespace [NAMESPACE] -l cnpg.io/cluster=[CLUSTER-NAME]
   
   A PVC stuck in Pending means Distributed File Storage (DFS) couldn’t provision the volume.

​

Common causes

• The CKS cluster has no CPU nodes with sufficient capacity. Provision CPU capacity through your usual CKS workflow.
• The CoreWeave Database (CWDB) add-on isn’t enabled on this CKS cluster. Confirm kubectl get crd | grep coreweave.com shows the CWDB CRDs. If not, request enablement through your customer Slack channel.
• The requested storage size exceeds available DFS capacity in the zone.

​

Resource is created in the wrong namespace

​

Symptom

​

Cause

​

Fix

kubectl delete cwdbcluster [CLUSTER-NAME] --namespace default
kubectl apply -f cwdb_cluster.yaml --namespace [NAMESPACE]

​

Application can’t connect to the database

​

Symptom

​

What to check

1. Confirm the database is Ready:
   kubectl get cwdbcluster [CLUSTER-NAME] --namespace [NAMESPACE]
   
2. Verify the Service exists:
   kubectl get svc [CLUSTER-NAME]-pooler-rw --namespace [NAMESPACE]
   
3. Check that your application is connecting to the pooler, not the direct database Service. Application traffic should go to [CLUSTER-NAME]-pooler-rw or [CLUSTER-NAME]-pooler-ro. The uri field in the [CLUSTER-NAME]-app-credentials Secret already points at the pooler.
4. Verify cross-namespace name resolution. From a pod in a different namespace, use the fully qualified name: [CLUSTER-NAME]-pooler-rw.[DB-NAMESPACE].svc.cluster.local.
5. Re-decode the credentials Secret. If the password has rotated, your application may be using a stale value:
   kubectl get secret [CLUSTER-NAME]-app-credentials \
     --namespace [NAMESPACE] \
     -o jsonpath='{.data.password}' | base64 -d
   

​

psql works from a debug pod but fails from the application

​

Symptom

​

Common causes

• The application is reading the wrong Secret. Confirm it mounts [CLUSTER-NAME]-[DBNAME]-credentials for read-write traffic ([CLUSTER-NAME]-app-credentials for the default dbName: app) or [CLUSTER-NAME]-[DBNAME]-credentials-ro for read-only traffic to replicas.
• The application has a NetworkPolicy that blocks egress to the database namespace. Check NetworkPolicies in the application’s namespace.
• The application is configured with a hard-coded hostname or port that doesn’t match the pooler Service.

​

On-demand backup stays in Pending

​

Symptom

kubectl get cwdbbackup [BACKUP-NAME] --namespace [NAMESPACE]

​

What to check

1. Confirm the source database is Ready: an on-demand backup can’t start if the database is unhealthy.
2. Check the backup status detail:
   kubectl describe cwdbbackup [BACKUP-NAME] --namespace [NAMESPACE]
   
   Look for events such as BackupFailed or quota errors.
3. Check whether you’re over the on-demand backup quota for the database. Delete unneeded backups, or contact your CoreWeave account team to raise the quota.

​

Restore takes too long

​

Symptom

​

Notes

• Restore time scales with database size and the write-ahead log (WAL) replay distance from the base backup. A small database restored from a recent base backup completes quickly. Restoring a multi-TiB database from older base backups can take hours.
• The new database only becomes Ready after the bootstrap completes. Don’t cut application traffic over until the new CWDBCluster reports Ready.
• If a restore appears stuck (no progress for more than 30 minutes for a small database), escalate through your customer Slack channel with the new database name, the spec.postgres.restore.sourceClusterName, and namespace.

​

Pods aren’t spread across distinct nodes

​

Symptom

kubectl get pods --namespace [NAMESPACE] -l cnpg.io/cluster=[CLUSTER-NAME] -o wide

​

Common causes

• You added a custom spec.affinity block that turned off the default anti-affinity rules.
• The CKS cluster doesn’t have enough CPU nodes for all instances. The scheduler falls back to co-locating pods when no spread is possible.

​

Fix

​

Known issues

​

Database size doesn’t appear in the Cloud Console immediately after creation

​

Escalate an issue

• The database name and namespace.
• The full output of kubectl describe cwdbcluster [CLUSTER-NAME] --namespace [NAMESPACE].
• Relevant pod or backup status: kubectl get pods,cwdbbackup --namespace [NAMESPACE].
• A short description of what you expected to happen and what happened instead.