python-poetry/poetry · error · RuntimeError

Unable to find a suitable destination for "{path}" in {paths

Error message

Unable to find a suitable destination for "{path}" in {paths_csv(self._candidates)}

What it means

Raised as RuntimeError in SitePackages.make_candidates when strict=True, the path is relative, but the computed candidate list (candidate / path for each) is empty - i.e. there are no site directories to resolve the relative path against.

Source

Thrown at src/poetry/utils/env/site_packages.py:90

    def make_candidates(
        self, path: Path, writable_only: bool = False, strict: bool = False
    ) -> list[Path]:
        candidates = self._candidates if not writable_only else self.writable_candidates
        if path.is_absolute():
            for candidate in candidates:
                with contextlib.suppress(ValueError):
                    path.relative_to(candidate)
                    return [path]
            site_type = "writable " if writable_only else ""
            raise ValueError(
                f"{path} is not relative to any discovered {site_type}sites"
            )

        results = [candidate / path for candidate in candidates]

        if not results and strict:
            raise RuntimeError(
                f'Unable to find a suitable destination for "{path}" in'
                f" {paths_csv(self._candidates)}"
            )

        return results

    def distributions(
        self, name: str | None = None, writable_only: bool = False
    ) -> Iterable[metadata.Distribution]:
        path = list(
            map(
                str, self._candidates if not writable_only else self.writable_candidates
            )
        )

        yield from metadata.PathDistribution.discover(name=name, path=path)

    def find_distribution(

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Verify the Env actually has site-packages: check env.site_packages.candidates is non-empty.
2. Recreate or reload the env so purelib/platlib are discovered correctly.
3. Construct the SitePackages with explicit, existing purelib/platlib paths.
4. Avoid passing strict=True on an env you haven't confirmed has sites.

Example fix

// before - SitePackages with no candidates
sp = SitePackages(purelib=Path("/does/not/exist"))
sp.write_text(Path("foo.py"), "")  # -> RuntimeError (strict, empty)

// after
sp = SitePackages(purelib=env.site_packages.purelib)
sp.write_text(Path("foo.py"), "")

def site_packages_has_candidates(site_packages) -> bool:
    return len(site_packages.candidates) > 0 and all(p.exists() for p in site_packages.candidates)

def is_no_destination_runtime_error(e: Exception) -> bool:
    return isinstance(e, RuntimeError) and "Unable to find a suitable destination" in str(e)

try:
    site_packages._path_method_wrapper(rel_path, "write_text", data)
except RuntimeError as e:
    if "Unable to find a suitable destination" in str(e):
        # reload env / fix SitePackages construction first
        site_packages = reload_site_packages(env)
        site_packages.write_text(rel_path, data)
    else:
        raise

When it happens

Trigger: Calling make_candidates(path, strict=True) (directly or via _path_method_wrapper, which always sets strict=True) with a relative path when self._candidates is empty, so results=[]. Exact branch: site_packages.py:87-93.

Common situations: A SitePackages instance constructed with empty/missing purelib and platlib (broken env discovery); the env has no detectable site-packages directories; operating on a freshly created or partially-initialized env object.

Related errors

• {path} is not relative to any discovered {site_type}sites
• Unable to access any of {paths_csv(candidates)}
• Destination <fg=yellow>{path}</> exists and is not empty. Di
• Specified path '{path}' is not a valid {'directory' if is_di

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