Qdrant Snapshot Restore Returns an Empty Collection

The definition carries three qualifiers, and each one constrains your recovery plan. From the snapshots page, available as of v0.8.4: "Snapshots are tar archive files that contain data and configuration of a specific collection on a specific node at a specific time."

One collection. Not the instance, not a set of collections, not aliases: "A collection level snapshot only contains data within that collection, including the collection configuration, all points and payloads. Collection aliases are not included and can be migrated or recovered separately." If your retrieval service queries documents_current and that name is an alias pointing at documents_v7, the restore brings back the points and none of the routing.

One node. The same page says you "must create snapshots for each node separately when dealing with a single collection", and repeats it as an aside: "A single snapshot will contain only the data stored on the node on which the snapshot was created." A three node cluster with four collections produces twelve archives per restore point, and a backup job that calls one node on a cron schedule captures that node's share and reports green.

One instant. Creation is documented as a synchronous operation producing a tar archive, so everything written after the call is a gap you close from your ingestion pipeline rather than from the archive.

# Create a snapshot of one collection on THIS node
curl -X POST 'http://localhost:6333/collections/orders/snapshots?wait=true' \
  -H 'api-key: ********'

# List what this node holds
curl -X GET 'http://localhost:6333/collections/orders/snapshots' \
  -H 'api-key: ********'

Run that against every node, not against a load balancer in front of them. Where the archives land is worth deciding before you need them, because the default is a directory on the same disk as the data you are protecting.

storage:
  # Where snapshots land. Default ./snapshots, or /qdrant/snapshots in the Docker image.
  snapshots_path: /mnt/snapshots

  # Temporary files during snapshot creation. Available as of v1.3.0.
  temp_path: /mnt/scratch

Both keys have environment equivalents, QDRANT__STORAGE__SNAPSHOTS_PATH among them, which is the form to use under an orchestrator, and since v1.10.0 there is an S3 backend under storage.snapshots_config.snapshots_storage. Wherever it lands, the archive is a second full copy of the corpus with a different access model than the query API, which is why who is allowed to create and download those snapshots is a separate review.

There is a second artefact type, and the difference decides whether aliases are in your backup at all.

The alias row bites in production: the collection snapshot is the artefact a distributed cluster can produce, and it is the one without aliases in it.

Qdrant frames priority as conflict resolution: "When recovering a snapshot to a non-empty node, there may be conflicts between the snapshot data and the existing data", with the note that "The default priority may not be best for all situations." The three values, quoted whole: "replica: (default) prefer existing data over the snapshot", "snapshot: prefer snapshot data over existing data", "no_sync: restore snapshot without any additional synchronization."

The third carries a warning to read as written rather than softened. no_sync "is for specialized use cases and is not commonly used. It allows managing shards and transferring shards between clusters manually without any additional synchronization. Using it incorrectly will leave your cluster in a broken state."

The table adds the fourth case: leaving the parameter out.

The last row is the honest one. The documentation says the default is replica. The source says otherwise: at v1.19.0 SnapshotPriority derives Default with the #[default] attribute on the Snapshot variant, and lib/storage/src/content_manager/snapshots/recover.rs resolves the field with let priority = priority.unwrap_or_default();. The three shard-snapshot handlers in src/actix/api/snapshot_api.rs do the same, and the enum default is identical at every minor release tag from v1.12.0 through v1.19.0. We did not run a binary to see which reading governs yours, so we will not adjudicate it. Both support one conclusion: set priority explicitly on every restore.

The precondition turns this from superstition into mechanism. In recover.rs at v1.19.0, before the priority match runs, Qdrant builds other_active_replicas: replicas of this shard on peers other than this one whose state is Active or ReshardingScaleDown. If that list is empty it calls activate_shard(...), commented as there being no other active replicas so no de-sync is possible. The priority match sits in the else branch.

On a single node instance, or on any shard whose only replica is the one you just restored, priority never comes into play and the snapshot data lands whatever you passed. Setting priority=snapshot there is a correct habit but it is not what makes the restore work, and a single node restore that came back empty has a cause elsewhere: the endpoint, the collection name, or the archive you pointed at.

When there is another active replica, each arm does something specific.

The Replica arm takes the first other active replica and calls toc.request_shard_transfer(...) from that peer onto this one, commented as the replica being the source of truth the recovered data must sync with. That transfer replaces what you just unpacked, and if you created the target collection moments earlier so the restore had somewhere to go, it faithfully brings you zero points.

The Snapshot arm activates the restored shard, then computes replicas_to_keep as replication_factor - 1 and replicas_to_remove as other_active_replicas.len().saturating_sub(replicas_to_keep), issues request_remove_replica for that many peers and marks the rest Dead. Snapshot priority is not a passive preference: it removes or kills other replicas so the cluster converges on the copy you restored. Correct for a migration, destructive if you reached for it to repair one sick node.

The NoSync arm activates the shard and does nothing else, which is the whole of the warning quoted above.

# Qdrant names the archive <collection>-<peer id>-<timestamp>.snapshot
# and writes it under <snapshots_path>/<collection>/
curl -X PUT 'http://localhost:6333/collections/orders/snapshots/recover?wait=true' \
  -H 'api-key: ********' \
  -H 'Content-Type: application/json' \
  -d '{
    "location": "file:///qdrant/snapshots/orders/orders-3766212330831337-2026-08-30-09-12-04.snapshot",
    "priority": "snapshot"
  }'

Priority is not the only route to a collection with no points. An issue filed in August 2026 and still open reports that restoring a snapshot of a collection whose sharding_method is custom into a new collection name through the upload endpoint produces a target with correct configuration and no points, and that the target may hold only metadata files such as config.json, shard_key_mapping.json and version.info on disk. If you use custom sharding, restore into a scratch collection and count points before trusting that path.

The docs name three: recovery from a URL or local file, recovery from an uploaded file, and recovery during start-up. They are not interchangeable. The parameter you cannot afford to omit sits in a different place in each of the two REST paths, and does not exist on the third.

The first two rows differ in one detail that decides whether your priority setting is read at all. In the OpenAPI spec at v1.19.0, PUT /collections/{collection_name}/snapshots/recover declares only collection_name as a path parameter and wait as a query parameter; priority is a field on the SnapshotRecover body schema, next to location. On POST /collections/{collection_name}/snapshots/upload it is a query parameter alongside wait and checksum. Append ?priority=snapshot to the recover endpoint and nothing rejects it: the field is absent from the body and you get default behaviour.

That body schema carries two more fields worth wiring in. checksum takes an optional SHA256 hash Qdrant validates before recovery, which catches an archive truncated in transit. api_key is the credential used when fetching from a remote URL, so a URL restore between two secured clusters needs no opening up of the source.

One interface does not exist: at v1.19.0 the public Snapshots gRPC service exposes Create, List, Delete and their full-storage equivalents, and no recover RPC. Recovery is REST only, so a gRPC control plane has one exception in it.

curl -X POST 'http://{qdrant-url}:6333/collections/{collection_name}/snapshots/upload?priority=snapshot' \
  -H 'api-key: ********' \
  -H 'Content-Type:multipart/form-data' \
  -F 'snapshot=@/path/to/snapshot-2022-10-10.snapshot'

That is the docs' own upload example, placeholders included.

The one restore that cannot silently drop your data is the one you can use only on a single node. It goes through the CLI: --snapshot "accepts a list of pairs such as <snapshot_file_path>:<target_collection_name>", and "The target collection must be absent otherwise the program will exit with an error."

# Single node only. Target collection must not already exist.
./qdrant --snapshot /snapshots/orders-2026-08-30.snapshot:orders

# Same, but overwrite an existing collection
./qdrant --force-snapshot --snapshot /snapshots/orders-2026-08-30.snapshot:orders

# Whole-storage restore, also single node only
./qdrant --storage-snapshot /snapshots/full-snapshot-2026-08-30-11-20-51.snapshot

Run the first command against a storage directory that already holds a collection named orders and v1.19.0 panics in src/snapshots.rs with the exact text Collection orders already exists. Use --force-snapshot to overwrite it. The whole-storage restore raises a parallel message for an existing alias. That string is also the authority on the spelling: the documentation page writes the flag with an underscore, while the CLI struct in src/main.rs declares the field as force_snapshot with no case override, so the derived long flag is kebab-case. Use the hyphen.

The parser checks three things about each pair. Collection name is missing: {value} fires when there is no colon or when the part after it is empty, so --snapshot /snapshots/orders-2026-08-30.snapshot with no target name prints Collection name is missing: /snapshots/orders-2026-08-30.snapshot. Snapshot path is missing: {value} fires when the part before the colon is empty. Collection name must not contain slashes: {value} fires on a name with a path separator. The pair splits with rsplit_once(':'), on the last colon, so a path containing a colon parses and a collection name containing one never will.

The REST paths say the opposite in their own OpenAPI descriptions: "This will overwrite any data, stored on this node, for the collection. If collection does not exist - it will be created." No confirmation, no refusal, no flag. The strict path is the one unavailable exactly where clusters live.

Qdrant states the compatibility rule with a worked example: "Snapshots generated in one Qdrant cluster can only be restored to other Qdrant clusters running the same minor version or the next minor version. For instance, a snapshot captured from a v1.18.1 cluster can only be restored to clusters running version v1.18.x, where x is equal to or greater than 1, or v1.19.x."

The archive knows where it came from. At v1.19.0, snapshot creation writes CollectionVersion::current_raw() into the storage version file inside the tar, and that value is the crate version. Restore does not rewrite it, so the producing version travels with the artefact.

That window moves. v1.18.0 shipped 11 May 2026, v1.18.1 on 22 May, v1.18.2 on 4 June, v1.18.3 on 17 July and v1.19.0 on 5 August 2026. A snapshot taken against v1.18.1 is inside the documented window for a v1.19.x cluster and outside it once your estate reaches v1.20. Nothing about the archive changes that day; your ability to restore it does. Long-horizon retention against that cadence is an upgrade-path question: either keep a matching binary for every archive you intend to restore, or accept that older archives are inputs to a migration rather than backups.

The downgrade direction is a hard stop. At v1.19.0, loading a collection whose stored version is greater than the running application version panics with Collection version is greater than application version, so a rollback a minor back cannot read the collections the newer binary wrote.

One more open report belongs in the runbook. An issue filed in January 2026 and still open describes cluster snapshot restores from a three node, three shard, two replica setup that sometimes produce three replicas instead of two, inconsistently across shards and runs, leaving replicas in a Partial state. It is reported as intermittent with no stated root cause, so read cluster state after every restore rather than treating it as a defect tied to a version you can avoid.

Milvus moves the version constraint out of the release cadence and into a published matrix, which is easier to plan against and just as binding.

The v0.5.16 release, published 29 May 2026, is the interface to write against. Its README lists eight subcommands: check, create, delete, get, help, list, restore and server, and one global flag beyond help, --config, defaulting to backup.yaml. The development branch carries more than the release does, so pin the runbook to a tag.

Storage is configured in two halves. minio.storageType names the backend Milvus itself uses and minio.backupStorageType the backend the backup is written to, both taking local, minio, s3, aws, gcp, ali(aliyun), azure, tc(tencent) or gcpnative. Set them differently and crossStorage, false by default, permits the copy. Check the shipped defaults: accessKeyID and secretAccessKey are both minioadmin, bucketName is a-bucket, rootPath is files, port is 9000 and useSSL is false.

The constraint to size windows around is that there is no incremental mode. The request for incremental backup and restore was filed on 11 August 2025 and remains open, so every backup is a full copy and every restore a full write. For a corpus that grows monotonically, the backup window grows with it.

# Check the resolved config and the connections first
./milvus-backup check

./milvus-backup create -n orders_2026_08_30
./milvus-backup list

# Restore into suffixed collections, and bring the index back with the data
./milvus-backup restore --restore_index -n orders_2026_08_30 -s _recover

--restore_index is not optional in practice: the end-to-end guide at that tag says that without it you restore the index manually, which is the Milvus version of a restore that reports success and leaves you something you cannot query at production latency. On the wider engine choice, we compared how these engines compare on everything other than recovery elsewhere.

Start with the arithmetic. Your recovery time objective for a retrieval index is the elapsed time from incident to the collection serving queries at the recall you promised, and the comparison is restore against rebuilding the index from source documents. Measure both on your own hardware and corpus: time a restore of a real archive, then time a re-embed and re-index of the same data. We are not going to hand you throughput numbers, because we found no reproducible published figure for these engines at a stated corpus size and a made-up one sets your objective wrong. The cost side of the re-embed branch is what re-embedding the corpus from source actually costs.

One structural difference tilts that arithmetic. A Qdrant snapshot contains the collection configuration alongside the points, so a restored collection comes back with the HNSW and quantization settings it had. A PostgreSQL dump is not like that: pg_dump defines post-data items as including definitions of indexes, triggers, rules and constraints, so the dump carries the index definition and the index is built again at restore, which is why the pgvector index build is the part that takes hours.

Now the drill. Restore into a scratch collection, never over the live one, and verify with requests rather than with the restore's own status code.

# 1. Exact point count on the restored collection
curl -X POST 'http://localhost:6333/collections/orders_restore_drill/points/count' \
  -H 'api-key: ********' \
  -H 'Content-Type: application/json' \
  -d '{"exact": true}'

# 2. Per-shard replica states: every replica should read Active
curl -X GET 'http://localhost:6333/collections/orders_restore_drill/cluster' \
  -H 'api-key: ********'

# 3. Collection config, to confirm the index parameters came back with it
curl -X GET 'http://localhost:6333/collections/orders_restore_drill' \
  -H 'api-key: ********'

Step 2 is where the Partial replica state from that open cluster-restore issue would appear, and a point count will never make that check for you. A non-zero count is necessary and nowhere near sufficient: it proves the restore path ran.

Five checks make up the record worth keeping.

The last two turn this into an engineering control instead of a checkbox, and they need an artefact you may not have yet: a fixed set of queries with known-good results, which is the retrieval eval set you run against the restored collection. Without it, "the index came back" is an opinion.

Do this one this week. Take a collection snapshot on every node, restore it into a scratch collection with priority set explicitly in the right part of the request for the endpoint you chose, run the three calls above, and write the point count, the replica states and the date into the runbook beside the Qdrant version you ran them against. That last field expires: when your estate moves two minors on, today's archives stop being restorable. For the rest of our RAG systems work, including the retrieval quality side that decides what "recovered" even means, start at the pillar.