Skip to content

fix(core): auto-fallback to dense collection when Milvus lacks SparseFloatVector#364

Open
sjhddh wants to merge 1 commit into
zilliztech:masterfrom
sjhddh:fix/milvus-sparse-vector-fallback
Open

fix(core): auto-fallback to dense collection when Milvus lacks SparseFloatVector#364
sjhddh wants to merge 1 commit into
zilliztech:masterfrom
sjhddh:fix/milvus-sparse-vector-fallback

Conversation

@sjhddh

@sjhddh sjhddh commented Apr 30, 2026

Copy link
Copy Markdown

Summary

Closes #259.

When indexing a codebase against a Milvus server (or embedded MILVUS_LITE deployment) that does not implement SparseFloatVector, the server rejects hybrid collection creation with field data type: 104 is not supported. Today this surfaces to the user as a stringified [object Object] because the SDK returns a ResStatus rather than throwing a real Error, and the failure aborts indexing without any actionable message.

This PR makes that capability mismatch self-healing for the default case while still giving explicit opt-ins a clear, fixable error.

What changed

  • packages/core/src/vectordb/milvus-vectordb.ts
    • New exported MilvusUnsupportedSparseVectorError so callers can recognize the type-104 rejection programmatically.
    • createHybridCollection now wraps the Milvus SDK call, surfaces both thrown errors and non-Success ResStatus responses (fixing the original [object Object]), and converts the type-104 case into the typed error.
  • packages/core/src/context.ts
    • prepareCollection catches MilvusUnsupportedSparseVectorError and:
      • when HYBRID_MODE was the implicit default, logs a one-time warning, flips a per-instance hybrid override to false, and falls back to creating a dense collection (or reuses an existing one);
      • when the user explicitly set HYBRID_MODE=true, re-throws with guidance to upgrade Milvus or set HYBRID_MODE=false, rather than silently downgrading.
    • getIsHybrid() consults the instance override first, so all downstream insert/search paths in the same session route to the dense collection that was actually created.

Why not just improve the error message

A previous fork-only patch (Somebi/claude-context@886a459) replaced [object Object] with the real Milvus reason, but left the user stuck: hybrid is the default, so a perfectly serviceable Milvus server still cannot index anything until the user discovers HYBRID_MODE=false. This PR keeps the better error message and lets the index complete on its own.

Tradeoffs considered

  • The fallback is intentionally session-scoped, not persisted. We don't write env files or override the user's configuration on disk; on restart the same fallback kicks in idempotently (the dense collection already exists, so prepareCollection short-circuits).
  • The fallback is not taken when the user explicitly opts into hybrid mode. Silently downgrading an explicit HYBRID_MODE=true would mask a server-version problem the user cares about.
  • Detection is by error message substring (data type: 104). The Milvus error code for this rejection isn't versioned reliably, but the substring has been stable across releases that emit it.

Test plan

  • pnpm install && pnpm build:core — clean
  • pnpm --filter @zilliz/claude-context-core typecheck — clean
  • pnpm --filter @zilliz/claude-context-mcp typecheck — clean (no downstream breakage)
  • pnpm --filter @zilliz/claude-context-core test — 11/11 passing, including 4 new tests in context.hybrid-fallback.test.ts:
    • falls back to dense collection when HYBRID_MODE is unspecified and Milvus rejects type 104
    • reuses an existing dense collection on the fallback path
    • rethrows with guidance when HYBRID_MODE=true is explicit
    • does not catch unrelated errors from createHybridCollection
  • Manual end-to-end against a Milvus instance that lacks SparseFloatVector — not run locally; relies on the typed-error contract verified by the unit tests. Maintainers with access to such a deployment can confirm.

…FloatVector

Older self-hosted Milvus servers (and embedded MILVUS_LITE deployments) reject
SparseFloatVector with `field data type: 104 is not supported`. The current
hybrid-mode default (HYBRID_MODE unspecified) silently surfaces this as
`[object Object]` because the SDK returns a ResStatus rather than a real Error,
leaving the user with an unindexable codebase and no actionable message.

Detect the type-104 rejection in MilvusVectorDatabase.createHybridCollection and
throw a typed `MilvusUnsupportedSparseVectorError`. In Context.prepareCollection:

- when HYBRID_MODE was the implicit default, log a one-time warning, flip the
  per-instance hybrid flag to false, and create a dense collection so indexing
  can proceed;
- when the user explicitly set HYBRID_MODE=true, re-throw with guidance to
  upgrade Milvus or set HYBRID_MODE=false instead of silently downgrading.

Closes zilliztech#259
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

field data type: 104 is not supported

1 participant