microsoft/semantic-kernel · error · ServiceInitializationError

Expected {expected_storage_files} files for collection {coll

Error message

Expected {expected_storage_files} files for collection {collection_name}

What it means

Raised by USearchMemoryStore._read_collections_from_dir (ServiceInitializationError) during construction when a discovered collection does not have exactly the expected number of storage files (one .usearch index plus one .parquet table). The store pairs the two files per collection; a partial set means the persisted state is corrupt/incomplete, so it refuses to load.

Source

Thrown at python/semantic_kernel/connectors/memory_stores/usearch/usearch_memory_store.py:257

        # str cast is temporarily fix for https://github.com/unum-cloud/usearch/issues/196
        return Index.restore(str(path), view=False)

    def _read_collections_from_dir(self) -> dict[str, _USearchCollection]:
        """Read all collections from directory to memory.

        Raises:
            ValueError: If files for a collection do not match expected amount.

        Returns:
            Dict[str, _USearchCollection]: Dictionary with collection names as keys and
              their _USearchCollection as values.
        """
        collections: dict[str, _USearchCollection] = {}

        for collection_name, collection_files in self._get_all_storage_files().items():
            expected_storage_files = len(_CollectionFileType)
            if len(collection_files) != expected_storage_files:
                raise ServiceInitializationError(
                    f"Expected {expected_storage_files} files for collection {collection_name}"
                )
            parquet_file, usearch_file = collection_files
            if parquet_file.suffix == _collection_file_extensions[_CollectionFileType.USEARCH]:
                parquet_file, usearch_file = usearch_file, parquet_file

            embeddings_table, embeddings_id_to_label = self._read_embeddings_table(parquet_file)
            embeddings_index = self._read_embeddings_index(usearch_file)

            collections[collection_name] = _USearchCollection(
                embeddings_index,
                embeddings_table,
                embeddings_id_to_label,
            )

        return collections

    async def get_collections(self) -> list[str]:

View on GitHub (pinned to c028a0c7dc)

Solutions

Inspect the persist_directory and ensure each collection has both a `.usearch` and a `.parquet` file and nothing extra with those extensions.
Remove the incomplete collection's orphaned file(s) so the store can recreate it.
Re-derive/reseed the affected collection from source data after deleting the partial files.

Example fix

// before
store = USearchMemoryStore(persist_directory='/data/usearch')  # raises: 'my_docs' has 1 file
// after
// delete the orphaned /data/usearch/my_docs.usearch, then recreate + reseed
store = USearchMemoryStore(persist_directory='/data/usearch')

Defensive patterns

Strategy: try-catch

Validate before calling

from pathlib import Path
exts = {'.usearch', '.parquet'}
groups: dict[str, list[Path]] = {}
for p in Path(persist_dir).iterdir():
    if p.suffix in exts:
        groups.setdefault(p.stem.lower(), []).append(p)
bad = [n for n, fs in groups.items() if len(fs) != 2]
assert not bad, f'incomplete collections: {bad}'
store = USearchMemoryStore(persist_directory=persist_dir)

Try / catch

from semantic_kernel.exceptions import ServiceInitializationError
try:
    store = USearchMemoryStore(persist_directory=persist_dir)
except ServiceInitializationError as e:
    if 'Expected' in str(e):
        # quarantine the incomplete collection and retry
        ...

Prevention

Ensure clean shutdowns (call store.close()) so both files are written atomically.
Back up the persist_directory as a unit, never individual files.
Validate the directory has paired (.usearch + .parquet) files before constructing the store.

When it happens

Trigger: Constructing `USearchMemoryStore(persist_directory=...)` where some collection has only a .usearch file (or only a .parquet file), or has extra/orphaned files matching the storage extensions. Triggered at startup while scanning the directory.

Common situations: A previous process crashed during `close()`/save leaving only one of the two files written; manual deletion of one file; partial copy/restore of the data directory; leftover files from a format change.

Related errors

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/c2eb156508e02a20. Report an issue: GitHub.