MemPalace/mempalace · error · BackendMismatchError

qdrant marker is unreadable: {marker_path}

Error message

qdrant marker is unreadable: {marker_path}

What it means

Raised when the qdrant marker file (a small JSON file next to the palace that pins the palace to a specific Qdrant URL/namespace) exists but cannot be read or parsed. The backend treats an unreadable marker as a mismatch-protection failure rather than ignoring it, because silently proceeding could write to the wrong remote.

Source

Thrown at mempalace/backends/qdrant.py:1237

            "namespace": config.namespace,
            "palace_hash": self._palace_hash(palace),
            "remote_prefix": self._remote_collection_prefix(palace=palace, config=config),
        }

    def _marker_exists(self, palace: PalaceRef) -> bool:
        return bool(palace.local_path and os.path.isfile(self._marker_path(palace.local_path)))

    def _read_marker(self, palace: PalaceRef) -> Optional[dict]:
        if not palace.local_path:
            return None
        marker_path = self._marker_path(palace.local_path)
        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(

View on GitHub (pinned to 06cb6987f0)

Solutions

  1. Inspect the marker file (cat <palace>/qdrant-marker.json or equivalent) and check for truncation or conflict markers
  2. If contents are unrecoverable, delete the marker and reinitialize with get_collection(..., create=True) after confirming the remote collection still exists
  3. Fix filesystem permissions/ownership on the palace directory so the process can read it
  4. Exclude palace directories from sync/merge tools that can corrupt single-file JSON

Example fix

// before
# marker corrupted -> BackendMismatchError: qdrant marker is unreadable
col = backend.get_collection(palace, "drawers")
// after
# recover the remote target from Qdrant config, then re-pin the marker
rm palacedir/qdrant-marker.json
col = backend.get_collection(palace, "drawers", create=True)  # rewrites marker
Defensive patterns

Strategy: validation

Validate before calling

import json, os
def marker_readable(palace_path: str, marker_name: str) -> bool:
    p = os.path.join(palace_path, marker_name)
    if not os.path.isfile(p):
        return True  # absent marker is fine
    try:
        with open(p, encoding="utf-8") as f:
            return isinstance(json.load(f), dict)
    except (OSError, json.JSONDecodeError):
        return False

Try / catch

from mempalace.backends.base import BackendMismatchError
try:
    col = backend.get_collection(palace, name)
except BackendMismatchError as e:
    if "unreadable" in str(e):
        # repair: back up corrupt marker, delete it, re-pin with create=True
        ...

Prevention

When it happens

Trigger: _read_marker() hits an OSError (permissions, disk error, race where the file is removed mid-open) or json.JSONDecodeError (truncated/corrupted file, e.g. crash during write, manual editing, sync-tool conflict artifacts) while opening a collection or validating the marker target.

Common situations: Marker file corrupted by an interrupted write or power loss; file synced through Dropbox/git with merge-conflict contents; restrictive file permissions after copying a palace directory between users/machines; disk-full during marker write.

Related errors

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