MemPalace/mempalace · error · ValueError

milvus_consistency_level must be one of: {allowed}

Error message

milvus_consistency_level must be one of: {allowed}

What it means

Thrown by normalize_milvus_consistency_level() in mempalace/config.py when the configured Milvus consistency level does not match any of the known levels (typically Strong, Bounded, Session, Eventually, and their prefix aliases). The value is stripped and lowercased, then looked up in the _MILVUS_CONSISTENCY_LEVELS alias map; a miss raises ValueError listing the allowed canonical names. This guards the Milvus backend's read-consistency setting before it ever reaches the Milvus client.

Source

Thrown at mempalace/config.py:245

    "session": "Session",
    "bounded": "Bounded",
    "eventually": "Eventually",
}

# How many timestamped palace backups to retain before the oldest are
# pruned. Applies to the accumulating backups written by ``mempalace
# migrate`` and ``mempalace repair max-seq-id`` — see
# ``MempalaceConfig.max_backups``.
DEFAULT_MAX_BACKUPS = 10


def normalize_milvus_consistency_level(value) -> str:
    raw = str(value).strip() if value else DEFAULT_MILVUS_CONSISTENCY_LEVEL
    normalized = _MILVUS_CONSISTENCY_LEVELS.get(raw.lower())
    if normalized:
        return normalized
    allowed = ", ".join(_MILVUS_CONSISTENCY_LEVELS.values())
    raise ValueError(f"milvus_consistency_level must be one of: {allowed}")


def sqlite_read_uri(db_path: str) -> str:
    """Return a read-only ``file:`` URI for ``sqlite3.connect(..., uri=True)``.

    A bare ``f"file:{db_path}?mode=ro"`` mis-parses paths containing spaces or
    other URI-reserved characters — common in real home directories (a Windows
    user folder like ``First Last``, many macOS paths). ``pathname2url``
    percent-encodes the path and normalizes separators so the database opens on
    every platform.
    """
    from urllib.request import pathname2url

    db_path = os.fspath(db_path)
    return f"file:{pathname2url(db_path)}?mode=ro"


@lru_cache(maxsize=1)

View on GitHub (pinned to 06cb6987f0)

Solutions

1. Read the allowed list in the error message and use one of those exact canonical values (e.g. 'Strong', 'Bounded', 'Session', 'Eventually').
2. Check for typos, stray whitespace/quotes, or YAML type coercion in the milvus_consistency_level key of your config file.
3. Omit the setting entirely to accept the default (DEFAULT_MILVUS_CONSISTENCY_LEVEL) if you don't need a specific level.
4. If you need a level the map doesn't know (e.g. a new Milvus release), open an issue/PR to add the alias to _MILVUS_CONSISTENCY_LEVELS in mempalace/config.py.

Example fix

# before
config = {"milvus_consistency_level": "strict"}

# after
config = {"milvus_consistency_level": "Strong"}

from mempalace.config import _MILVUS_CONSISTENCY_LEVELS, normalize_milvus_consistency_level

def valid_level(value: str) -> bool:
    try:
        normalize_milvus_consistency_level(value)
        return True
    except ValueError:
        return False

assert valid_level(cfg.get("milvus_consistency_level", "Strong"))

def is_milvus_level(value: object) -> bool:
    return isinstance(value, str) and value.strip().lower() in {
        "strong", "bounded", "session", "eventually"
    }

try:
    level = normalize_milvus_consistency_level(raw)
except ValueError as exc:
    raise ConfigError(f"fix milvus_consistency_level: {exc}") from exc

When it happens

Trigger: Passing milvus_consistency_level="strict" (typo for 'strong'), "Eventually " with unusual casing is fine but a completely unknown word like "fast" is not; setting it via config file, MEMPALACE_* env var, or a MilvusBackend constructor argument with an unsupported level; passing an empty string (falsy) actually falls back to the default, so only non-empty unknown strings trigger it.

Common situations: Copy-pasting a consistency level from Milvus 2.x docs that this version's alias map doesn't include; upgrading Milvus which renames levels while MemPalace's map lags; typos in YAML/JSON config (unquoted values, trailing characters); CI config differing from local config.

Related errors

• ChromaBackend has been closed
• Milvus filter field {name!r} is not a safe identifier
• $in requires a non-empty list for {field!r}
• $nin requires a non-empty list for {field!r}
• embedding must be a non-empty 1D vector

AI-assisted analysis of MemPalace/mempalace@06cb6987f0 (2026-08-15). Data as JSON: /api/errors/933d0254bd80e884. Report an issue: GitHub.