sam local invoke: Usage & Common CI Errors

Run a Lambda function locally in a Lambda-like container.

sam local invoke runs one function locally inside a Docker container that emulates the Lambda runtime, with an event you supply - a fast way to test handlers in CI before deploy.

What it does

sam local invoke <FunctionId> starts a Lambda-emulation container, passes it the event (from --event or stdin), runs the handler, and prints the response and logs. It uses the artifacts from sam build (.aws-sam/build), so build first. It requires Docker on the host.

Common usage

# Invoke a function with an event file
sam local invoke MyFunction --event events/event.json

# Pipe an event from stdin
echo '{"key":"value"}' | sam local invoke MyFunction --event -

# Pass environment variable overrides
sam local invoke MyFunction -e event.json --env-vars env.json

Common error in CI: Docker not running / build not found

invoke fails with "Error: Running AWS SAM projects locally requires Docker. Have you got it installed and running?" or "Function ... not found / no build artifacts". Fix: ensure the CI runner has a running Docker daemon (and can pull the Lambda emulation image), and run sam build before sam local invoke so the build directory exists. On runners without Docker, fall back to unit-testing the handler directly instead of sam local.

Key options

Related guides