The incident does not start with a red cluster. It starts with users saying search got worse. One tenant has slow queries, another gets empty results, a node is hot, merges are behind, and recall changed after a backfill. OpenSearch vector failures often look like relevance problems before they look like infrastructure problems.

Short Version

OpenSearch vector search fails through familiar distributed-system paths: wrong shard count, hot shards, uneven tenant distribution, memory pressure, merge backlog, poor filters, stale embeddings, and under-tested HNSW settings.

The recovery playbook should separate availability, latency, recall, and security. A green cluster can still return poor candidates. A fast query can still miss relevant documents. A relevance regression can still be caused by shard distribution, memory pressure, or filters.

OpenSearch vector internals and available metrics depend on version and deployment model — the k-NN engine in use (Faiss, Lucene, or the deprecated nmslib) changes which metrics and tuning parameters are relevant, and a self-managed cluster exposes different operational metrics than Amazon OpenSearch Service’s managed CloudWatch integration. Confirm which engine and deployment model is in play before applying troubleshooting steps from a mismatched context.

Situation

Search infrastructure teams are used to latency incidents, indexing backlogs, and shard imbalance. Vector search adds a quality dimension that can fail without an obvious outage.

For RAG and semantic search, users notice missing context, irrelevant answers, and inconsistent results across tenants. Those symptoms require both search relevance debugging and infrastructure triage.

The Problem

Vector search creates new ways for a cluster to be technically up and functionally wrong:

  • Candidate search can under-return after filters.
  • Shard distribution can affect latency and candidate diversity.
  • HNSW tuning can change recall.
  • Memory pressure can make tail latency unstable.
  • Segment merges can compete with query traffic.
  • Backfills can change data distribution and hot nodes.
  • Tenant skew can turn one customer into a cluster-wide problem.

The operational trap is treating every complaint as “the embedding model is bad.” Sometimes the model is fine and the search system is sick.

Core Technical Explanation

An OpenSearch vector query fans out across shards, runs local candidate retrieval, combines results, and applies the rest of the query pipeline. If shards are uneven, filters are selective, or local candidate counts are too low, final results can degrade.

flowchart TD
    Query[vector query] --> Fanout[fan out to shards]
    Fanout --> Hot[hot shard or node]
    Fanout --> Cold[normal shards]
    Hot --> LocalA[local candidates]
    Cold --> LocalB[local candidates]
    LocalA --> Merge[global result merge]
    LocalB --> Merge
    Merge --> Filters[filters and ranking]
    Filters --> Results[user results]

Shard count controls how data and queries distribute. Too few shards can produce large recovery units and hot spots. Too many shards create overhead and fanout. The right answer depends on data volume, query rate, tenant skew, replicas, and node count.

Recall loss can come from vector parameters, candidate counts, filters, stale embeddings, or uneven data. It is not one metric. Teams need a fixed query set and a way to compare results before and after changes.

Hot nodes often come from shard placement, tenant skew, or query routing. A single large tenant or popular corpus can dominate one shard if routing and index design are naive.

In Practice

Run incidents through a layered triage:

Layer 1: availability. Cluster health, rejected requests, node failures, disk watermarks, and snapshot or allocation issues.

Layer 2: latency. Search latency by route, shard, node, index, and query class. Separate lexical, vector, and hybrid traffic.

Layer 3: freshness. Indexing lag, refresh behavior, backfill progress, and embedding version distribution.

Layer 4: recall. Query-set results, under-return rate, empty-result rate, and known-good candidates missing from output.

Layer 5: security. Tenant filters, entitlement filters, deletion filters, and negative tests.

Do not rebalance, resize, reindex, and retune HNSW all at once. Preserve enough evidence to know which action fixed the problem.

Where It Breaks

Failure modeUser symptomOperator signalRecovery
Wrong shard countSlow or inconsistent searchFanout overhead or huge shardsReindex with better shard plan
Hot shardOne tenant or corpus slowNode-level skewSplit, route, or isolate workload
Memory pressureTail latency spikesHeap or native memory pressureResize, reduce load, tune workload
Merge backlogLatency worsens during indexingMerge activity and I/O pressureThrottle backfill or adjust refresh
Recall degradationRelevant docs disappearQuery-set regressionTune candidates, filters, or index settings
Poor filtersEmpty or unauthorized resultsHigh filter drop-offFix query builder and tests
Stale embeddingsOld content ranksEmbedding lag by model versionResume backfill or rollback route

Security and Tenancy Notes

Security failures can masquerade as relevance fixes. Broadening filters to improve recall can accidentally expand the authorization boundary. Tenant, region, entitlement, deletion state, and compliance rules must remain hard constraints during incident response.

For multi-tenant workloads, keep hot-tenant remediation separate from authorization. Moving a tenant to a new index, shard strategy, or domain should preserve query-time filters and audit behavior.

Cost Notes

Operational recovery has cost:

  • Reindexing consumes compute and storage.
  • Extra replicas increase spend.
  • Larger nodes may hide bad shard design.
  • Isolated tenant indexes or domains multiply baseline cost.
  • Higher candidate counts improve recall but raise query CPU.

The cheapest fix is often query and shard discipline. The most expensive fix is repeatedly scaling the cluster because no one wants to reindex.

Observability Notes

Useful dashboards include:

  • Latency by route: lexical, vector, hybrid.
  • Latency by index, shard, and node.
  • Query count and error rate by tenant.
  • Candidate count and final result count.
  • Empty-result and under-return rate.
  • Segment count and merge pressure.
  • Refresh and indexing lag.
  • Embedding model-version distribution.
  • Hot shard and disk watermark views.
  • Query-set recall checks.

Observability should connect symptoms to ownership. Search relevance, platform, database, and application teams need the same incident vocabulary.

Backup, Restore, and DR Notes

Some failures require reindexing rather than restore. A wrong shard count or bad mapping usually cannot be fixed in place. The runbook should include creating a replacement index, replaying data, validating relevance, and switching aliases.

Snapshots matter when the cluster or index is lost. Rebuild matters when the index design is wrong. Production DR needs both paths.

Decision Checklist

  • Is the issue availability, latency, recall, security, or freshness?
  • Which tenants and query classes are affected?
  • Are hot shards or nodes visible?
  • Did a backfill, mapping change, model change, or shard change happen recently?
  • Are filters dropping most vector candidates?
  • Does exact or higher-recall validation find the missing documents?
  • Can the fix be done with settings, or does it require reindexing?
  • Is rollback an alias switch?
  • Does recovery preserve tenant boundaries?
  • What metric proves the incident is resolved?

What to Do Next

Problem: OpenSearch vector search can be technically up (green cluster, no errors) while functionally wrong — degraded recall, hot shards, or stale embeddings show up as “search got worse” complaints, not outages.

Solution: Triage in layers — availability, latency, freshness, recall, security — rather than jumping straight to “the embedding model is bad,” and preserve evidence before rebalancing, resizing, reindexing, and retuning HNSW all at once.

Proof: A fixed query set shows recall back at baseline after remediation, and the specific layer (shard, memory, filter, or freshness) that caused the regression is identified, not just papered over by scaling nodes.

Action: This week, confirm recall is tracked as its own SRE signal (query-set regression, not just latency and error rate), since a green cluster with degraded recall won’t show up in typical uptime dashboards.

Sources to Verify