SAM Doctor

ERROR REFERENCE

Python runtime binary is incompatible with the build runtime

sam build looked for a Python interpreter matching the function's declared runtime and the ones it found did not satisfy the constraint. The machine has Python — just not the version the template promises Lambda.

WHAT IT MEANS

What this error means

Binary validation failed for python, searched for python in following locations ... which did not satisfy constraints for runtime: python3.12 names both sides of the mismatch: the interpreters on PATH, and the runtime the function declares. SAM builds with a matching interpreter so compiled dependencies match what Lambda runs; a close-but-different version is exactly what it refuses.

FIX

How to fix it

  1. Install the matching interpreter and make sure a python3.12 (or the version your template names) is on PATH where the build runs — in CI, a setup-python step with that exact version.
  2. Or build in a container: 
    sam build --use-container
    The build then runs inside an image that ships the right interpreter, at the cost of needing Docker.
  3. Or update the template's Runtime: when the function should genuinely move to the Python you have - a deliberate runtime upgrade, not a workaround.

AUTOMATE THE TRIAGE

Diagnose this automatically

SAM Doctor recognizes the constraint wording (high confidence) and separates it from dependency-resolution and wheel-build failures. Runs locally; no AWS access, no log upload. 

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

RELATED