{"record":{"id":"872901f8ec60c8e1","repo":"agentscope-ai/agentscope","slug":"path-path-file-exists-but-is-not-a-file","errorCode":null,"errorMessage":"Path {path_file} exists but is not a file.","messagePattern":"Path (.+?) exists but is not a file\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/agentscope/embedding/_file_cache.py","lineNumber":78,"sourceCode":"        \"\"\"Store the embeddings with the given identifier.\n\n        Args:\n            embeddings (`List[Embedding]`):\n                The embeddings to store.\n            identifier (`JSONSerializableObject`):\n                The identifier to distinguish the embeddings, which will be\n                used to generate a hashable filename, so it should be\n                JSON serializable (e.g. a string, number, list, dict).\n            overwrite (`bool`, defaults to `False`):\n                Whether to overwrite existing embeddings with the same\n                identifier. If `True`, existing embeddings will be replaced.\n        \"\"\"\n        filename = self._get_filename(identifier)\n        path_file = os.path.join(self.cache_dir, filename)\n\n        if os.path.exists(path_file):\n            if not os.path.isfile(path_file):\n                raise RuntimeError(\n                    f\"Path {path_file} exists but is not a file.\",\n                )\n\n            if overwrite:\n                np.save(path_file, embeddings)\n                await self._maintain_cache_dir()\n        else:\n            np.save(path_file, embeddings)\n            await self._maintain_cache_dir()\n\n    async def retrieve(\n        self,\n        identifier: JSONSerializableObject,\n    ) -> List[Embedding] | None:\n        \"\"\"Retrieve the embeddings with the given identifier. If not found,\n        return `None`.\n\n        Args:","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/embedding/_file_cache.py#L60-L96","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the printed path with ls -la to confirm what non-file object occupies it","Remove or rename the offending directory/fifo entry","Use a dedicated, empty cache_dir per cache instance so nothing else writes into it","If concurrent processes manage the dir, add locking or separate cache dirs to avoid layout races"],"exampleFix":"# before\ncache = FileCache(cache_dir=\"./cache\")  # ./cache/<id> is a directory\nawait cache.store(\"myid\", emb)\n\n# after\nimport shutil\nbad = os.path.join(\"./cache\", cache._get_filename(\"myid\"))\nif os.path.exists(bad) and not os.path.isfile(bad):\n    shutil.rmtree(bad)\nawait cache.store(\"myid\", emb)","handlingStrategy":"validation","validationCode":"import os\npath_file = os.path.join(cache.cache_dir, cache._get_filename(identifier))\nif os.path.exists(path_file) and not os.path.isfile(path_file):\n    raise RuntimeError(f\"cache path corrupted: {path_file}\")","typeGuard":null,"tryCatchPattern":"try:\n    await cache.store(identifier, embeddings, overwrite=True)\nexcept RuntimeError as e:\n    if \"exists but is not a file\" in str(e):\n        # clean up and retry once\n        shutil.rmtree(path_file, ignore_errors=True)\n        await cache.store(identifier, embeddings, overwrite=True)\n    else:\n        raise","preventionTips":["Dedicate one empty directory per cache instance","Never create subdirectories inside cache_dir","Run cache maintenance (clear/_maintain_cache_dir) from a single owner process"],"tags":["cache","filesystem","embedding","agentscope"],"backgroundTag":"path-is-not-a-file","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}