python-poetry/poetry · error · ValueError

Invalid cache key

Error message

Invalid cache key

What it means

Raises ValueError in CacheClearCommand.handle() when the cache argument has more than 3 colon-separated parts (root:package:version is the max). The else branch at line 93-94 catches any key with 4+ segments as invalid. This is a malformed-input guard on the cache key format.

Source

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

            raise RuntimeError(
                "Only specifying the package name is not yet supported. "
                "Add a specific version to clear"
            )
        elif len(parts) == 3:
            package = canonicalize_name(parts[1])
            version = parts[2]

            if not cache.has(f"{package}:{version}"):
                self.line(f"No cache entries for {package}:{version}")
                return 0

            delete = self.confirm(f"Delete cache entry {package}:{version}", True)
            if not delete:
                return 0

            cache.forget(f"{package}:{version}")
        else:
            raise ValueError("Invalid cache key")

        return 0

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Use exactly the format root:package:version (3 parts) or root (1 part with --all).
2. Check for stray colons in the argument; quote the argument if package names contain colons.

Example fix

# before (error)
poetry cache clear pypi:requests:2.28.0:extra-segment
# after
poetry cache clear pypi:requests:2.28.0

def validate_cache_key_format(cache_arg: str) -> None:
    parts = cache_arg.split(":") if cache_arg else []
    if len(parts) > 3:
        raise ValueError(f"Cache key has {len(parts)} parts; maximum is 3 (root:package:version)")

def is_valid_cache_key_format(cache_arg: str) -> bool:
    parts = cache_arg.split(":") if cache_arg else []
    return len(parts) <= 3

When it happens

Trigger: Running `poetry cache clear pypi:requests:2.28.0:extra` or any cache argument with more than 3 colon-separated parts.

Common situations: User appends extra segments by mistake, includes a colon in a package/version name, or misunderstands the expected key format.

Related errors

• You can only specify one package when using the --extras opt
• Invalid config setting format: {config_setting}. Config sett
• {root} is not a valid repository cache
• Add the --all option if you want to clear all cache entries
• Only specifying the package name is not yet supported. Add a

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