[Python] SAM CLI Lambda container cannot connect to LocalStack Secrets Manager on macOS:

"Could not connect to the endpoint URL: http://localhost:4566/

I'm developing a FastAPI-based Lambda function using AWS SAM CLI for local testing on macOS, with LocalStack emulating Secrets Manager. The deployment script starts LocalStack in Docker mode, creates a secret, and launches the API with sam local start-api. The health endpoint works, but the /login endpoint (which fetches a secret from LocalStack) fails with a 500 error and timeout. Lambda logs show:

[ERROR] 2025-08-03T17:56:02.055Z bfbe9fac-b862-4586-8b22-7f959a7cce4b 15. Error fetching user secret: Could not connect to the endpoint URL: "http://localhost:4566/"
[ERROR] 2025-08-03T17:56:09.151Z bfbe9fac-b862-4586-8b22-7f959a7cce4b 33. Unexpected error in login: Could not connect to the endpoint URL: "http://localhost:4566/"
Function 'AuthFunction' timed out after 20 seconds


The SAM CLI Lambda container seems unable to connect to LocalStack at localhost:4566, while awslocal commands from the host work fine.

Environment:

• macOS Sonoma 14.5 (M3 chip)
• Docker Desktop 28.3.2
• SAM CLI 1.124.0
• LocalStack CLI 4.7.0
• Python 3.12
• Boto3 1.40.1

Relevant code in main.py:

secrets_endpoint = "http://localhost:4566" if is_local else None
secrets_client = boto3.client("secretsmanager", endpoint_url=secrets_endpoint, region_name="us-east-1")


def get_user(username: str) -> Optional[dict]:
logger.info("11. Fetching user secret for: %s", username)
try:
response = secrets_client.get_secret_value(SecretId="UserCredentials")
users = json.loads(response["SecretString"])
logger.info("12. Secret retrieved: %s", {k: v for k, v in users.items() if k == username})
return users.get(username)
except Exception as e:
logger.error("13. Error fetching user secret: %s", str(e))
return None


05_manage_api.sh:

if [ "$LOCAL_ONLY" == "true" ]; then
echo " Starting local API..."
TEMPLATE_FILE="${PWD}/.aws-sam/build/template.yaml"
ENV_PATH="${PWD}/env.json"
PORT=3000

while lsof -i :$PORT > /dev/null 2>&1; do
echo "⚠️ Port $PORT is in use. Trying port $((PORT + 1))..."
PORT=$((PORT + 1))
done
echo "✅ Using port $PORT for API."

sam local start-api \
--template-file "${TEMPLATE_FILE}" \
--docker-network host \
--env-vars "${ENV_PATH}" \
--port "${PORT}" \
--host 127.0.0.1 \
--static-dir public \
--layer-cache-basedir "${HOME}/.aws-sam/layers-pkg" \
--container-host host.docker.internal
else
echo " Remote API setup will be handled by CloudFormation stack (no action taken here)."
fi


LocalStack is running (status: ✔ running, name: "localstack-main", IP: 172.17.0.2), and awslocal secretsmanager get-secret-value --secret-id UserCredentials works from the host.

What I've tried:

• --docker-network host in sam local start-api
• --container-host host.docker.internal
• Increased sleep times (15 seconds) and readiness checks for LocalStack
• Verified LocalStack logs show no errors and "Ready."
• Tested with dummy credentials in ~/.aws/credentials

How can I make the SAM CLI Lambda container connect to LocalStack on macOS? Is there a better way to configure the Docker network or endpoint? Any insights would be appreciated!

Continue reading...