{"id":"36ce3fb75403ad94","repo":"python-poetry/poetry","slug":"pep517-build-of-a-dependency-failed","errorCode":null,"errorMessage":"PEP517 build of a dependency failed","messagePattern":"PEP517 build of a dependency failed","errorType":"exception","errorClass":"IsolatedBuildBackendError","httpStatus":null,"severity":"error","filePath":"src/poetry/utils/isolated_build.py","lineNumber":231,"sourceCode":"            builder = ProjectBuilder.from_isolated_env(\n                env, source, runner=quiet_subprocess_runner\n            )\n\n            with redirect_stdout(stdout):\n                env.install(\n                    builder.build_system_requires, constraints=build_constraints\n                )\n\n                # we repeat the build system requirements to avoid poetry installer from removing them\n                env.install(\n                    builder.build_system_requires\n                    | builder.get_requires_for_build(distribution),\n                    constraints=build_constraints,\n                )\n\n                yield builder\n        except BuildBackendException as e:\n            raise IsolatedBuildBackendError(source, e) from None\n","sourceCodeStart":213,"sourceCodeEnd":232,"githubUrl":"https://github.com/python-poetry/poetry/blob/92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54/src/poetry/utils/isolated_build.py#L213-L232","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the wrapped BuildBackendException via error.exception.exception for the real backend traceback.","Ensure the declared build-backend and its build-system.requires are installed and compatible with your Python.","Provide a prebuilt wheel for the target platform so the source build is skipped (upgrade/refresh caches).","Fix the source package (missing files, syntax errors) if it is your own."],"exampleFix":"# before - backend references a missing module\n[build-system]\nrequires = [\"setuptools\"]\nbuild-backend = \"myproj.build\"   # file does not exist\n# after\n[build-system]\nrequires = [\"setuptools>=61\"]\nbuild-backend = \"setuptools.build_meta\"","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"from poetry.utils.isolated_build import IsolatedBuildBackendError\ntry:\n    with isolated_builder(source) as builder:\n        builder.build('wheel')\nexcept IsolatedBuildBackendError as e:\n    # e.source is the project path; e.exception is the BuildBackendException\n    cause = e.exception.exception\n    print('backend failed on', e.source, '->', cause)\n    raise","preventionTips":["Ensure the declared build-backend and its requires are installed and Python-compatible.","Provide prebuilt wheels to avoid source builds for hard platforms.","Validate that the source tree is complete (no missing modules) before building."],"tags":["pep517","build-backend","wheel","isolated-build","sdist"],"analyzedSha":"92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54","analyzedAt":"2026-08-04T20:33:34.072Z","schemaVersion":2}