agentscope-ai/agentscope · error · RuntimeError

Path {path_file} exists but is not a file.

Error message

Path {path_file} exists but is not a file.

What it means

Raised by FileCache.store when the derived cache path exists on disk but is not a regular file (e.g. it is a directory, symlink to a directory, or a special file). The cache assumes every identifier maps to a flat .npy file, so a non-file path makes saving impossible.

Source

Thrown at src/agentscope/embedding/_file_cache.py:78

        """Store the embeddings with the given identifier.

        Args:
            embeddings (`List[Embedding]`):
                The embeddings to store.
            identifier (`JSONSerializableObject`):
                The identifier to distinguish the embeddings, which will be
                used to generate a hashable filename, so it should be
                JSON serializable (e.g. a string, number, list, dict).
            overwrite (`bool`, defaults to `False`):
                Whether to overwrite existing embeddings with the same
                identifier. If `True`, existing embeddings will be replaced.
        """
        filename = self._get_filename(identifier)
        path_file = os.path.join(self.cache_dir, filename)

        if os.path.exists(path_file):
            if not os.path.isfile(path_file):
                raise RuntimeError(
                    f"Path {path_file} exists but is not a file.",
                )

            if overwrite:
                np.save(path_file, embeddings)
                await self._maintain_cache_dir()
        else:
            np.save(path_file, embeddings)
            await self._maintain_cache_dir()

    async def retrieve(
        self,
        identifier: JSONSerializableObject,
    ) -> List[Embedding] | None:
        """Retrieve the embeddings with the given identifier. If not found,
        return `None`.

        Args:

View on GitHub (pinned to e90f1c7592)

Solutions

1. Inspect the printed path with ls -la to confirm what non-file object occupies it
2. Remove or rename the offending directory/fifo entry
3. Use a dedicated, empty cache_dir per cache instance so nothing else writes into it
4. If concurrent processes manage the dir, add locking or separate cache dirs to avoid layout races

Example fix

# before
cache = FileCache(cache_dir="./cache")  # ./cache/<id> is a directory
await cache.store("myid", emb)

# after
import shutil
bad = os.path.join("./cache", cache._get_filename("myid"))
if os.path.exists(bad) and not os.path.isfile(bad):
    shutil.rmtree(bad)
await cache.store("myid", emb)

import os
path_file = os.path.join(cache.cache_dir, cache._get_filename(identifier))
if os.path.exists(path_file) and not os.path.isfile(path_file):
    raise RuntimeError(f"cache path corrupted: {path_file}")

try:
    await cache.store(identifier, embeddings, overwrite=True)
except RuntimeError as e:
    if "exists but is not a file" in str(e):
        # clean up and retry once
        shutil.rmtree(path_file, ignore_errors=True)
        await cache.store(identifier, embeddings, overwrite=True)
    else:
        raise

When it happens

Trigger: Calling await cache.store(identifier, embeddings, overwrite=...) when <cache_dir>/<hash>.npy is actually a directory or FIFO; commonly caused by the cache_dir itself being pre-populated with directories or by a filename collision with an existing directory name.

Common situations: Sharing a cache directory with other tooling that creates subdirectories, restoring a cache from a corrupted archive, or manually creating folders inside cache_dir; also nested runs pointing different caches at the same path with different layouts.

Related errors

• File {path_file} does not exist.
• "AgentScopeEmbedding requires `model` in the config to be an
• f"AgentScopeEmbedding `model` must be an EmbeddingModelBase,
• "AgentScope embedding model returned no embeddings."
• Embedding model returned {len(response.embeddings)} vectors

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/872901f8ec60c8e1. Report an issue: GitHub.