What causes a 'collection not found' error immediately after a collection was reportedly created successfully in a distributed cluster?

In a distributed Qdrant cluster, creating a collection is a metadata operation that goes through Raft consensus. The client sends the create request to whichever node it is connected to, that node forwards it to the Raft leader if it is not the leader, the leader commits the metadata change, and the change is then applied across the cluster as the Raft log is replicated to followers. The create call may return success as soon as the leader has committed the entry, but the other nodes apply the change asynchronously as they receive and apply the Raft log entry. If the client then immediately sends a query to a different node - or if the client's connection is load-balanced to a node that has not yet applied the metadata - that node may not yet know about the collection and will return 'collection not found'. The collection exists in the cluster's metadata, but not yet on the node the query reached.

The mechanism is that Qdrant's metadata plane is strongly consistent through Raft, but the application of committed entries on each node is not instantaneous. The window is normally very short - typically milliseconds - but it can be longer under load, during a leader election, or if a node is lagging. The symptom is intermittent: the same create-then-query sequence succeeds most of the time and fails occasionally, which makes it hard to reproduce. A related cause is querying a node that is not part of the same Raft group, which can happen if the cluster is misconfigured or if a client is pointing at a node that is in a different cluster. Another related cause is querying an alias that has not yet been created or updated - aliases are also metadata and go through the same consensus path. The distinction matters because the fixes are different: waiting and retrying handles propagation delay, but a misconfigured client or cluster needs a configuration fix.

The trade-off is between availability and consistency of metadata operations. Qdrant commits metadata through Raft, so a create is durable and consistent once acknowledged, but the acknowledgement is from the leader's perspective, and the followers catch up asynchronously. Making the create block until every node has applied it would eliminate the propagation window but would make metadata operations slower and less available. The common mistake is to treat the create-then-query sequence as atomic at the application level. It is not, and the application should either retry the query on a 'collection not found' or wait for the collection to be visible before proceeding. The second mistake is to assume the problem is a client cache when it is actually the server's metadata propagation - both are possible, and the diagnosis is to query the same node and a different node and compare. The third mistake is to blame the cluster when the client is pointing at a node that is not part of it, which is a configuration issue, not a consistency issue. Version note: the exact behavior of metadata operations during a leader election, and the API for checking cluster state, have changed across Qdrant releases. Some versions expose a readiness endpoint or cluster info that tells you whether the node has applied the latest metadata.

Version-dependent: the metadata propagation behavior and the APIs for inspecting cluster state have changed across Qdrant releases. In earlier versions, the consensus implementation used a single Raft group for the cluster; more recent versions have moved toward per-collection consensus. The exact window during which a newly created collection is not visible on all nodes, and the way to query for readiness, depend on the version. If you are building automation around create-then-query, use a retry with backoff rather than assuming immediate visibility, and check whether your version exposes a readiness signal.