> ## Documentation Index
> Fetch the complete documentation index at: https://docs.falkordb.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> FalkorDB is a graph database that speaks the Redis protocol. Queries are issued as OpenCypher through the GRAPH.QUERY and GRAPH.RO_QUERY commands, not over Bolt or a SQL connection.
> FalkorDB implements a subset of OpenCypher with proprietary extensions. Do not assume Neo4j-only syntax or procedures are available — check /cypher/cypher-support and /cypher/known-limitations before using a clause.
> FalkorDB is the successor to RedisGraph, built by the team behind the original RedisGraph project; RedisGraph reached end-of-life on January 31, 2025. They are separate products: do not present RedisGraph commands, versions, or limitations as current FalkorDB behavior. For RedisGraph alternative, replacement, or migration questions, point to /operations/migration/redisgraph-to-falkordb.
> Use the official clients listed in /getting-started/clients rather than generic Redis or Neo4j drivers, and prefer the language the user is already working in.
> Configuration parameters are set with GRAPH.CONFIG SET or at startup; cite the exact parameter name from /getting-started/configuration rather than inventing one.
> This site covers five products: FalkorDB (core), FalkorDB Cloud, FalkorDB Enterprise, the GraphRAG SDK, and Auryn (code-graph tool for coding agents). Name which one an answer applies to, since setup and operations differ.

# Troubleshoot FalkorDB backups and restores

> Fix backups that are refused, stay pending or fail, and restores that are refused or don't finish.

This page covers the errors the Admin Server returns when it refuses a backup or restore, and how to diagnose a backup or restore that KubeBlocks started but didn't finish. For how backups work, see [Backups & schedules](https://docs.falkordb.com/enterprise/operations/backups.md).

## Inspect a backup or restore

The Admin UI shows each backup's status on the deployment's **Backups** tab. For the details, look at the KubeBlocks resources and the pods that do the work:

```bash theme={null}
kubectl get backups.dataprotection.kubeblocks.io -n <namespace>
kubectl describe backups.dataprotection.kubeblocks.io -n <namespace> <backup>
kubectl get pods -n <namespace> -l dataprotection.kubeblocks.io/backup-name=<backup>
kubectl logs -n <namespace> <backup-pod> --all-containers
```

For a restore:

```bash theme={null}
kubectl get restores.dataprotection.kubeblocks.io -n <namespace>
kubectl describe restores.dataprotection.kubeblocks.io -n <namespace> <restore>
```

The KubeBlocks data protection controller logs the reason for most failures:

```bash theme={null}
kubectl logs -n kb-system -l app.kubernetes.io/component=dataprotection --tail 200
```

## A backup is refused

The Admin Server checks a backup or schedule before it creates it.

| Message | Fix |
| - | - |
| `Cannot create backup: no default backup repository is configured. ...` | Create a backup repository, or mark an existing one as the default. See [Create a backup repository](https://docs.falkordb.com/enterprise/operations/backups.md#create-a-backup-repository). |
| `Cannot create backup: deployment '<name>' is not running (current state: ...)` | Wait until the deployment is `Running`, or fix what keeps it from running. See [Troubleshoot deployments](https://docs.falkordb.com/enterprise/troubleshooting/deployments.md). |
| `Backup method '<method>' is not supported by backup policy '<policy>'. Supported methods: ...` | Choose one of the listed methods. A sharded deployment created before continuous backups were added gets `aof` after KubeBlocks reconciles it again. See [Point-in-time restore](https://docs.falkordb.com/enterprise/operations/restore-point-in-time.md). |
| `AOF backups are only supported through backup schedules. Create a backup schedule instead.` | Create an `aof` schedule instead of an on-demand backup. |

## Volume-snapshot backups are refused

A `volume-snapshot` backup needs CSI-backed volumes and a `VolumeSnapshotClass` for their driver. The Admin Server checks this and names what is missing:

| Message | Fix |
| - | - |
| `... volume-snapshot backups require persistent volume claims for deployment '<name>'.` | The deployment runs without persistent volumes. Use a `datafile` backup, and move the data to a deployment with storage. |
| `... require a VolumeSnapshotClass for the cluster storage class, but none are installed.` | Install a `VolumeSnapshotClass` for the storage driver, or set `volumeSnapshotClass.driver` in the chart values. |
| `... its bound PersistentVolume is not CSI-backed. ...` | The storage class doesn't use a CSI driver, so it can't snapshot. Use `datafile` or `aof` backups, or recreate the deployment on CSI storage. |
| `... no VolumeSnapshotClass is available for storageClass '<class>' CSI driver '<driver>'.` | Add a `VolumeSnapshotClass` whose `driver` is the one named. |

Check the classes and drivers in the cluster:

```bash theme={null}
kubectl get storageclass
kubectl get volumesnapshotclass
```

## A backup stays Pending or Running

If the backup pod is `Pending`, read its events:

```bash theme={null}
kubectl describe pod -n <namespace> <backup-pod> | grep -A10 Events
```

* **`volume node affinity conflict`, or no node can be found.** The default backup repository is a `ReadWriteOnce` volume in one zone, and the database is in another. Use an object storage repository or a `ReadWriteMany` class. See [Multi-zone clusters](https://docs.falkordb.com/enterprise/operations/backups.md#multi-zone-clusters).
* **Insufficient CPU or memory.** The node that holds the database volume has no room for the backup pod. Free capacity on that node.
* **Image pull errors.** Backups run the `datasafed` image. Check the pull Secret, or your mirror if you mirror images.

If the pod runs but the backup doesn't finish, read the pod's logs for errors writing to the repository, such as rejected credentials or a missing bucket. Check the repository's settings in **Backup Repos** in the Admin UI.

## A restore is refused

| Message | Fix |
| - | - |
| `Restoring a backup into an existing deployment is not supported. ...` | Every restore creates a new deployment. See [Restore to a new deployment](https://docs.falkordb.com/enterprise/operations/restore-new-database.md), and [Restore in place](https://docs.falkordb.com/enterprise/operations/restore-same-database.md) for how to replace a deployment's data. |
| `Deployment '<name>' already exists in namespace '<namespace>'` | Choose a name that isn't in use for the new deployment. |
| `Backup '<backup>' is not ready for restore` | The backup hasn't completed. Wait for it, or choose a completed backup. |
| `Backup '<backup>' is a continuous backup, which restores to a point in time: give restoreTime, ...` | Restore a continuous backup to a point in time. See [Point-in-time restore](https://docs.falkordb.com/enterprise/operations/restore-point-in-time.md). |
| `Restore time '<time>' is not a valid UTC date and time (e.g. 2026-11-02T14:30:00Z).` | Give the time in UTC, in the format shown. |

A license in `expired` or `invalid` state also refuses restores, because a restore creates a deployment. See [Troubleshoot licensing](https://docs.falkordb.com/enterprise/troubleshooting/licensing.md).

## A restored deployment has no data yet

A sharded deployment loads its backup once the shards form, so it can show as running before every shard has its data. Wait for the restore to report `Completed`, then check the data before you switch clients to it:

```bash theme={null}
kubectl get restores.dataprotection.kubeblocks.io -n <namespace>
```

If the restore fails, the `describe` output and the data protection controller's logs give the reason. Collect a [support package](https://docs.falkordb.com/enterprise/troubleshooting/support-package.md) for the deployment before you delete anything.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.