Introduction

exec format error in an AWS Go Lambda almost always means the uploaded executable was built for the wrong operating system or CPU architecture. Lambda runs Linux binaries, so a Go program compiled on macOS or Windows without cross-compiling will start fine locally but fail immediately in AWS.

Why the error appears

Go builds native binaries for the current machine by default. If you run:

go build -o bootstrap

on macOS, the output is a macOS executable. Lambda cannot run that file inside its Linux runtime, so you get exec format error when the function starts.

The fix is to build for Linux and for the same architecture configured in Lambda.

Build for the correct Lambda target

For a custom runtime using provided.al2 or provided.al2023, compile the binary explicitly for Linux. For x86_64:

GOOS=linux GOARCH=amd64 go build -o bootstrap main.go
zip function.zip bootstrap

For arm64:

GOOS=linux GOARCH=arm64 go build -o bootstrap main.go
zip function.zip bootstrap

After that, make sure the Lambda function configuration uses the same architecture as the binary you built.

Package the binary correctly

With a custom runtime, the executable must be named bootstrap and must sit at the root of the zip archive. A valid package layout looks like this:

function.zip
  bootstrap

You can verify the archive contents before uploading:

unzip -l function.zip

If the archive contains dist/bootstrap or another nested path, Lambda may not find the executable the way you expect.

Verify the artifact locally

A quick local check can save a deployment cycle. Use the file command to inspect the binary:

file bootstrap

A correct x86_64 build should report a Linux executable for x86-64. A correct arm64 build should report a Linux executable for aarch64 or ARM64. If the output says Mach-O or PE, the binary was built for macOS or Windows instead of Linux.

Minimal Go Lambda example

Here is a small handler using the AWS Lambda Go package:

1package main
2
3import (
4	"context"
5
6	"github.com/aws/aws-lambda-go/lambda"
7)
8
9func handler(ctx context.Context) (string, error) {
10	return "ok", nil
11}
12
13func main() {
14	lambda.Start(handler)
15}

Build and package it for a custom runtime like this:

GOOS=linux GOARCH=amd64 go build -o bootstrap main.go
chmod +x bootstrap
zip function.zip bootstrap

The chmod step is not usually the cause of exec format error, but it is still a good packaging habit because Lambda needs an executable file.

Managed runtime versus custom runtime details

Different runtime models have slightly different packaging expectations. Older managed Go runtimes used a handler binary name, while custom runtimes expect bootstrap. If your deployment tool, runtime choice, binary name, and architecture do not agree, Lambda startup fails even when the source code itself is correct.

That is why it is worth checking all of these together:

• Lambda runtime
• Lambda architecture
• binary file name
• zip archive layout

Common Pitfalls

• Building on macOS or Windows without setting GOOS=linux.
• Uploading an amd64 binary to an arm64 Lambda function, or the reverse.
• Zipping the wrong directory structure so bootstrap is not at the archive root.
• Focusing on application code before verifying the build artifact itself.

Summary

• 'exec format error usually means the Go executable was built for the wrong OS or architecture.'
• Build Lambda artifacts with GOOS=linux and the correct GOARCH.
• For custom runtimes, name the executable bootstrap and place it at the zip root.
• Use file and unzip -l to verify the artifact before deploying it.