python-poetry/poetry · error · ValueError

Specified path '{path}' is not a valid {'directory' if is_di

Error message

Specified path '{path}' is not a valid {'directory' if is_directory else 'file'}.

What it means

Raised as ValueError in helpers.ensure_path when the given path either does not exist at all, or exists but its type does not match the is_directory flag (a file passed where a directory was required, or vice versa). It is a path precondition check used at internal call sites.

Source

Thrown at src/poetry/utils/helpers.py:140

        path = Path(os.path.relpath(package.source_url, root)).as_posix()
        return f"{package.version} {path}"

    pretty_version: str = package.full_pretty_version
    return pretty_version


def paths_csv(paths: list[Path]) -> str:
    return ", ".join(f'"{c!s}"' for c in paths)


def ensure_path(path: str | Path, is_directory: bool = False) -> Path:
    if isinstance(path, str):
        path = Path(path)

    if path.exists() and path.is_dir() == is_directory:
        return path

    raise ValueError(
        f"Specified path '{path}' is not a valid {'directory' if is_directory else 'file'}."
    )


def is_dir_writable(path: Path, create: bool = False) -> bool:
    try:
        if not path.exists():
            if not create:
                return False
            path.mkdir(parents=True, exist_ok=True)

        with tempfile.TemporaryFile(dir=str(path)):
            pass
    except OSError:
        return False
    else:
        return True

View on GitHub (pinned to 92b74dcfe3)

Solutions

Verify the path exists: 'Path(p).exists()'; create it if it should be there.
Match the is_directory flag to what the path actually is (or what the caller requires).
Resolve the path to absolute before checking: 'Path(p).resolve()'.
Create the parent directory or the file itself before calling ensure_path.

Example fix

// before
ensure_path("/tmp/missing-dir", is_directory=True)  # -> ValueError

// after
Path("/tmp/missing-dir").mkdir(parents=True, exist_ok=True)
ensure_path("/tmp/missing-dir", is_directory=True)

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

def path_is_valid(path, is_directory: bool) -> bool:
    p = Path(path)
    return p.exists() and p.is_dir() == is_directory

# before ensure_path:
assert path_is_valid(target, is_directory=is_directory), f"{target} missing or wrong type"

Type guard

def is_ensure_path_value_error(e: Exception) -> bool:
    return isinstance(e, ValueError) and "is not a valid" in str(e) and ("directory" in str(e) or "file" in str(e))

Try / catch

from poetry.utils.helpers import ensure_path

try:
    p = ensure_path(target, is_directory=is_directory)
except ValueError as e:
    if "is not a valid" in str(e):
        # create the missing file/dir, or fix the is_directory flag
        if is_directory:
            Path(target).mkdir(parents=True, exist_ok=True)
        else:
            Path(target).touch()
        p = ensure_path(target, is_directory=is_directory)
    else:
        raise

Prevention

Create the target file or directory before calling ensure_path.
Match the is_directory flag to the path's actual (or intended) type.
Resolve to absolute and confirm existence with Path.exists() first.
Validate parent directories exist before asserting a file path.

When it happens

Trigger: Calling ensure_path(path, is_directory=...) where not path.exists(), or path.is_dir() != is_directory. Exact branch: helpers.py:137-142. Used wherever Poetry needs to assert an externally-supplied path is a usable file or directory before proceeding.

Common situations: Passing a path string that hasn't been created yet; pointing at a file when the API needs a directory (e.g. a site-packages dir); pointing at a directory when a single file is required; relative path resolved against the wrong cwd so it appears missing.

Related errors

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