Databases
Fix refused database deployments, unhealthy PostgreSQL clusters, reader and failover refusals, recovery and restore refusals, and query console errors.
Use this page when a Database service does not deploy, does not become healthy, or refuses an action in its Data, Replicas or Backups tab. Each entry starts with the message you see.
this cluster doesn't run CloudNativePG yet: install it from the cluster's settings (Install CloudNativePG), then deploy again
Cause: A Postgres database runs only on CloudNativePG, so the deploy is refused with a 409 on a cluster without the operator. The service's Settings tab shows an alert with an Install CloudNativePG button.
Fix: Open the cluster, select Settings, and under CloudNativePG select Install CloudNativePG. Run the Install command on the cluster's first server and paste the One-time token at the NebulaCtrl token: prompt. Then deploy again.
Verify: The Operator row reads CloudNativePG 1.30.1 installed.
database-unhealthy
Cause: The deployment fails with this blocker when CloudNativePG does not report every instance ready within 15 minutes. The message is one of <ready> of <total> instances ready, waiting for the CloudNativePG Cluster object to be created, waiting for CloudNativePG to report the cluster's status, cluster phase is "<phase>", or CloudNativePG's own reason.
Fix: In the environment's namespace on the cluster, run k3s kubectl -n <namespace> get clusters.postgresql.cnpg.io,pods,pvc and read the events of the one that is not ready. Remove the cause, then deploy again.
Verify: The deployment reaches healthy and the Data tab lists tables.
restoring <source> to <time> did not finish: <reason>
Cause: A point-in-time restore failed after its 2-hour start deadline. Postgres stops at the first transaction after the chosen moment and fails when the archive holds none. The object store may also be unreachable or lack a base backup from before the moment.
Fix: Delete the new database; the original is untouched. In the Backups tab of the original, select Restore to this moment… and choose a moment at or before its newest activity.
Verify: The new database deploys and reaches healthy.
replicas at most 5 readers (6 instances total) are supported
Cause: A change set staged more than 5 readers on a Postgres database. A value below 1 reads replicas a CloudNativePG database runs 1 to 6 instances; to turn it off, stop the service instead of scaling it to 0. Valkey, MySQL and MongoDB run as a single instance.
Fix: Stage 1 to 6 instances in the Replicas tab. To turn the database off, stop the service.
Verify: The change set stages without the refusal.
serviceId needs at least one reader to fail over to
Cause: Automatic failover is refused with a 422 while the database has no reader. serviceId automatic failover only applies to a Postgres database is the refusal for another engine.
Fix: Stage at least one reader, then stage Automatic failover.
Verify: The toggle stages and the change set applies.
<pod> is not a current reader of this database
Cause: Promote to writer is refused when the pod is not a current reader. The agent adds <pod> is already the target primary and <pod> is fenced and cannot be promoted. For another engine the API answers only a Postgres database has readers to promote.
Fix: Reload the Replicas tab and promote a pod that it lists as a reader.
Verify: The promoted pod shows as the writer; the former writer rejoins as a reader.
this cluster's Barman Cloud Plugin isn't ready yet; point-in-time recovery needs it
Cause: The API answers 409 when you turn on point-in-time recovery or restore before the plugin finishes installing. The operator and the plugin install separately.
Fix: On the cluster, run k3s kubectl -n cnpg-system rollout status deploy/barman-cloud, or re-run the installer.
Verify: The rollout reports success, and Turn on succeeds.
accessKeyId objectStoreId, accessKeyId and secretAccessKey are all required to turn point-in-time recovery on
Cause: Turn on point-in-time recovery needs an object store and a key. The text continues: create a key scoped to this database's prefix only, never the organization's main one. In production only an admin can turn it on.
Fix: In Turn on point-in-time recovery, choose an Object store and enter an Access key ID and Secret access key scoped to the prefix. Then select Turn on.
Verify: The toast reads Point-in-time recovery is on.
point-in-time recovery is off for <service> in <environment>, so its archive stops growing and no new restore can start
Cause: A restore needs an archive that is still written. Restoring is an admin action in every environment.
Fix: Turn on Point-in-time recovery in the Backups tab, then restore a moment after it was on.
Verify: Restore to this moment… creates the new database.
at <time> is before the earliest moment this archive can restore to, <time>; choose that moment or a later one
Cause: The moment you chose predates the archive. The related refusal at <time> is in the future; choose a moment that has already happened rejects a later one.
Fix: Choose a moment inside the window the archive reports.
Verify: The restore starts.
this cluster's agent is too old to restore a database to a point in time; nothing was created. Update the agent from the cluster's settings, then restore again.
Cause: The cluster's agent does not report the restore capability. A deploy of a restored database is refused in the same way, because it would start empty.
Fix: Select Update agent on the cluster, then restore again. See agent updates.
Verify: The restore request succeeds.
database service <slug> has no healthy release in environment <environment>; deploy it first
Cause: The Data tab shows this with Nothing ran. Deploy the database and wait for it to be healthy, then run it again. A related refusal reads the cluster running environment <environment> is not connected right now; nothing was sent, try again once it reconnects.
Fix: Deploy the database and wait until it is healthy, or reconnect the cluster.
Verify: Run returns rows.
Running queries here needs a higher role; ask an admin.
Cause: The console shows this under a 403. A deployer can query non-production environments; only an admin can query production.
Fix: Ask an admin to run the query, or change your role.
Verify: Run returns rows.
the console is read-only: <KEYWORD> statements are not run here; start with one of SELECT, WITH, EXPLAIN, SHOW, TABLE, VALUES
Cause: The Postgres and MySQL console refuses a statement that does not start with a read keyword; MySQL also allows DESCRIBE and DESC. run one statement at a time: a semicolon may only end the query rejects a second statement. Use a migration or the CLI for writes.
Fix: Rewrite the query as one read statement.
Verify: Run returns rows.
the console is read-only: <COMMAND> is not one of the read commands it runs
Cause: Valkey accepts only an allowlist of read commands. MongoDB accepts one JSON document with find or countDocuments. A different key reads "<key>" is not a console key; use find, countDocuments, filter, projection, sort, limit, skip, and $where, $function and $accumulator are refused.
Fix: Use a read command, or a document such as {"find": "<collection>", "filter": {}}.
Verify: Run returns rows.
Queries run on the primary in a read-only transaction, stop after 5 s, return at most 500 rows, and are written to the activity log.
Cause: This caption under the editor states the console limits. A query running past 5 seconds is cancelled by the database, and a result stops at 500 rows or 512 KiB. A query over 16 KiB is refused with query must be valid UTF-8 of at most 16384 bytes.
Fix: Add a filter or a LIMIT, or select fewer columns.
Verify: The result grid shows the complete result.
database service <slug> has no <KEY> variable in environment <environment>, so nothing can sign in to it; set one and redeploy
Cause: The generated password variable is missing, so the connection URL cannot sign in. Services connect through DATABASE_URL_PG_<NAME>, DATABASE_URL_MYSQL_<NAME>, DATABASE_URL_MONGO_<NAME> or REDIS_URL_<NAME>.
Fix: Set the named variable in the database's Variables tab, then redeploy.
Verify: The Data tab lists tables.
engineVersion Postgres <major> has no CloudNativePG-maintained image pinned; only 16 and 18 do
Cause: The control plane has no CloudNativePG image for that major. A stored version it cannot run reads <engine> <major> is not a version this control plane runs.
Fix: Use Postgres 16 or 18. For the second message, restore a dump into a new database.
Verify: The deploy passes admission.
a backup or restore is already in progress for this volume in this environment
Cause: The API answers 409 while a volume backup or restore is queued or running. A restore without downtimeAccepted reads downtimeAccepted must be true: a restore quiesces every workload on the volume, wipes it, then extracts the archive, and leaves the service stopped if the restore fails.
Fix: Wait for the running job, and accept the downtime when you restore.
Verify: The backup or restore starts.