python-poetry/poetry · error · IsolatedBuildBackendError

PEP517 build of a dependency failed

Error message

PEP517 build of a dependency failed

What it means

The isolated_builder() context manager wraps ProjectBuilder work; when the PEP 517 build backend itself raises (BuildBackendException from the `build` library), it is re-raised as IsolatedBuildBackendError(source, exception). generate_message() prefixes the detail with 'PEP517 build of a dependency failed'. This means the backend (setuptools/flit/hatchling/poetry-core) errored while actually producing the wheel/sdist, distinct from failing to install build dependencies (error 124).

Source

Thrown at src/poetry/utils/isolated_build.py:231

            builder = ProjectBuilder.from_isolated_env(
                env, source, runner=quiet_subprocess_runner
            )

            with redirect_stdout(stdout):
                env.install(
                    builder.build_system_requires, constraints=build_constraints
                )

                # we repeat the build system requirements to avoid poetry installer from removing them
                env.install(
                    builder.build_system_requires
                    | builder.get_requires_for_build(distribution),
                    constraints=build_constraints,
                )

                yield builder
        except BuildBackendException as e:
            raise IsolatedBuildBackendError(source, e) from None

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Inspect the wrapped BuildBackendException via error.exception.exception for the real backend traceback.
2. Ensure the declared build-backend and its build-system.requires are installed and compatible with your Python.
3. Provide a prebuilt wheel for the target platform so the source build is skipped (upgrade/refresh caches).
4. Fix the source package (missing files, syntax errors) if it is your own.

Example fix

# before - backend references a missing module
[build-system]
requires = ["setuptools"]
build-backend = "myproj.build"   # file does not exist
# after
[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"

from poetry.utils.isolated_build import IsolatedBuildBackendError
try:
    with isolated_builder(source) as builder:
        builder.build('wheel')
except IsolatedBuildBackendError as e:
    # e.source is the project path; e.exception is the BuildBackendException
    cause = e.exception.exception
    print('backend failed on', e.source, '->', cause)
    raise

When it happens

Trigger: Building a project (or a dependency from source, when no compatible wheel is available) where the backend crashes: missing source files, syntax errors in the package, backend version incompatibility, or a backend bug. Triggered via `poetry build` or during resolution that forces an sdist build.

Common situations: A dependency without a wheel for your platform whose sdist backend fails; corrupted/incomplete source checkout; backend requires a newer Python; backend not declared correctly in pyproject.

Related errors

• Failed to install {requirements}.
• Invalid build config setting '{value}'. It must be a valid J
• Unknown metadata version: {dist.metadata_version}
• {wheel.filename} is not a supported wheel for this platform.
• Unable to parse build tag: {wheel.build_tag}

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