MemPalace/mempalace · error · BackendMismatchError

qdrant marker is missing remote target metadata

Error message

qdrant marker is missing remote target metadata

What it means

Raised when the marker identifies itself as a qdrant marker but its "qdrant" field is missing or not a JSON object. The qdrant field carries the remote target metadata (URL, namespace) used for drift detection; without it the backend cannot verify the palace is being pointed at the same Qdrant deployment, so it refuses to open.

Source

Thrown at mempalace/backends/qdrant.py:1249

        if not os.path.isfile(marker_path):
            return None
        try:
            with open(marker_path, encoding="utf-8") as f:
                marker = json.load(f)
        except (OSError, json.JSONDecodeError) as exc:
            raise BackendMismatchError(f"qdrant marker is unreadable: {marker_path}") from exc
        return marker if isinstance(marker, dict) else {}

    def _validate_marker_target(self, palace: PalaceRef, config: _QdrantConfig) -> None:
        marker = self._read_marker(palace)
        if marker is None:
            return
        if marker.get("backend") != self.name:
            raise BackendMismatchError("qdrant marker does not identify the qdrant backend")
        expected = self._marker_target(palace, config)
        actual = marker.get("qdrant")
        if not isinstance(actual, dict):
            raise BackendMismatchError("qdrant marker is missing remote target metadata")
        mismatched = [
            key for key, expected_value in expected.items() if actual.get(key) != expected_value
        ]
        if mismatched:
            details = ", ".join(mismatched)
            raise BackendMismatchError(
                "qdrant marker remote target does not match current configuration "
                f"({details}); keep MEMPALACE_QDRANT_URL and namespace consistent "
                "or use a fresh palace directory"
            )

    def _write_marker(self, palace: PalaceRef, config: _QdrantConfig) -> None:
        if not palace.local_path:
            return
        os.makedirs(palace.local_path, exist_ok=True)
        try:
            os.chmod(palace.local_path, 0o700)
        except (OSError, NotImplementedError):

View on GitHub (pinned to 06cb6987f0)

Solutions

  1. Delete the stale marker and re-pin the palace with get_collection(..., create=True) against the intended Qdrant server (verify the remote collection exists first)
  2. Upgrade mempalace so markers are written with the current schema
  3. Avoid hand-editing marker files; let the backend write them

Example fix

// before
# marker: {"backend": "qdrant"}  (no "qdrant" target block)
col = backend.get_collection(palace, "drawers")  # raises
// after
rm palacedir/qdrant-marker.json
col = backend.get_collection(palace, "drawers", create=True)  # writes full marker
Defensive patterns

Strategy: validation

Validate before calling

def marker_has_target(palace_path: str, marker_name: str) -> bool:
    try:
        with open(os.path.join(palace_path, marker_name), encoding="utf-8") as f:
            m = json.load(f)
        return isinstance(m.get("qdrant"), dict)
    except (OSError, json.JSONDecodeError):
        return False

Try / catch

from mempalace.backends.base import BackendMismatchError
try:
    backend.get_collection(palace, name)
except BackendMismatchError as e:
    if "missing remote target metadata" in str(e):
        reinitialize_marker()  # delete marker, reopen with create=True

Prevention

When it happens

Trigger: Marker JSON parses and backend == "qdrant", but marker.get("qdrant") is None, a string, a list, etc. Causes: hand-edited marker, marker written by an older version that did not include target metadata, or partial/truncated write that still left valid JSON.

Common situations: Upgrading mempalace from a version whose marker schema lacked the qdrant target block; scripts that regenerate marker files without the full schema; manual attempts to fork a palace by copying and editing the marker.

Related errors

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