SAM Doctor

ERROR REFERENCE

Binary validation failed: failed to build wheel

A dependency needed compiling and the build machine could not do it — no prebuilt wheel exists for this platform/Python combination, and building from source failed. Cryptography, numpy-adjacent, and database-driver packages are the usual suspects.

WHAT IT MEANS

What this error means

pip prefers prebuilt wheels; when none matches the target platform and Python version, it compiles from source — which needs compilers, headers, and sometimes Rust. CI runners and laptops often lack those, and even a successful local build can produce binaries that do not match Lambda's Linux runtime, which is the deeper reason SAM validates this step at all.

FIX

How to fix it

  1. Build in the Lambda-matching container: 
    sam build --use-container
    The build image ships the toolchain and produces Linux-correct binaries. This is the fix that removes the whole class.
  2. Or pin a version that ships a wheel for your runtime - newer releases of the failing package often added wheels for recent Python versions; check the package's PyPI files page.
  3. Align the Python version with what the package supports — a brand-new Python minor often lacks wheels for a few months, and downgrading the function runtime one minor is sometimes the pragmatic answer.

AUTOMATE THE TRIAGE

Diagnose this automatically

SAM Doctor recognizes the wheel-build failure (high confidence) within the Python build family. Runs locally; no AWS access, no log upload. 

python -m pip install sam-doctor
sam-doctor diagnose build.log --format markdown

RELATED