python-poetry/poetry · error · ValueError

{root} is not a valid repository cache

Error message

{root} is not a valid repository cache

What it means

Raises ValueError in CacheClearCommand.handle() when the first segment of the cache argument (the 'root') resolves to a path that is not relative to the repository_cache_directory. This is a path-traversal guard: Path.relative_to() raises ValueError if the cache_dir is not under repository_cache_directory, and Poetry re-raises with a clear message naming the offending root.

Source

Thrown at src/poetry/console/commands/cache/clear.py:49

    ]

    def handle(self) -> int:
        cache = self.argument("cache")

        if cache:
            parts = cache.split(":")
            root = parts[0]
        else:
            parts = []
            root = ""

        config = Config.create()
        cache_dir = config.repository_cache_directory / root

        try:
            cache_dir.relative_to(config.repository_cache_directory)
        except ValueError:
            raise ValueError(f"{root} is not a valid repository cache")

        cache = FileCache(cache_dir)

        if len(parts) < 2:
            if not self.option("all"):
                raise RuntimeError(
                    "Add the --all option if you want to clear all cache entries"
                )

            if not cache_dir.exists():
                self.line(
                    f"No cache entries for {root}" if root else "No cache entries"
                )
                return 0

            # Calculate number of entries
            entries_count = sum(
                len(files) for _path, _dirs, files in os.walk(str(cache_dir))

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Use a valid cache root name without path separators or '..' segments — typically a repository/source name like 'pypi'.
2. Use `poetry cache clear --all` to clear the entire cache without specifying a root.

Example fix

# before (error)
poetry cache clear ../something
# after
poetry cache clear pypi:requests:2.28.0
# or clear everything
poetry cache clear --all

from pathlib import Path

def validate_cache_root(root: str, repository_cache_dir: Path) -> None:
    cache_dir = repository_cache_dir / root
    cache_dir.relative_to(repository_cache_dir)  # raises ValueError if traversal

from pathlib import Path

def is_valid_cache_root(root: str, repository_cache_dir: Path) -> bool:
    try:
        (repository_cache_dir / root).relative_to(repository_cache_dir)
        return True
    except ValueError:
        return False

When it happens

Trigger: Running `poetry cache clear ../foo` or any cache argument whose first colon-separated segment contains path traversal characters (.., /, etc.) that escape the repository cache directory. The check is cache_dir.relative_to(config.repository_cache_directory).

Common situations: User passes a filesystem path instead of a cache name, uses '..' segments, or the cache name contains slashes that resolve outside the cache root.

Related errors

• Invalid cache key
• Expected a value for {setting_key} setting.
• Attempting to write {path} outside of the target directory T
• Refusing to extract {member.name}: would write outside {dest
• Refusing symlink {member.name}: target {member.linkname} out

AI-assisted analysis of python-poetry/poetry@92b74dcfe3 (2026-08-04). Data as JSON: /data/errors/40965fc59199edd1.json. Report an issue: GitHub.