Bug: SAM CLI Finch Detection Fails on Linux with Rootless Containerd

[robbrad]

AWS SAM CLI versions 1.151.0 and 1.154.0 fail to detect Finch on Ubuntu Linux (arm64) when using rootless containerd, despite Finch being properly installed and functional. The error message is:

Error: Running AWS SAM projects locally requires a container runtime. Do you have Docker or Finch installed and running?

Environment

• OS: Ubuntu 24.04.3 LTS
• Architecture: aarch64 (ARM64)
• SAM CLI Version: 1.151.0 and 1.154.0 (both tested)
• Finch Version: v1.14.1
• Finch Installation Method: Ubuntu apt repository (runfinch-finch package)
• Containerd: Rootless mode with nerdctl backend
• Python: 3.11.10

Finch Configuration

Finch is installed via the official Ubuntu apt repository and configured with rootless containerd:

# Finch installation
curl -fsSL https://artifact.runfinch.com/deb/GPG_KEY.pub | sudo gpg --dearmor -o /usr/share/keyrings/runfinch-finch-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/runfinch-finch-archive-keyring.gpg arch=$(dpkg --print-architecture)] https://artifact.runfinch.com/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/runfinch-finch.list
apt-get update
apt-get install -y runfinch-finch containerd

# Rootless containerd setup
loginctl enable-linger participant
mkdir -p /run/user/$(id -u participant)
export XDG_RUNTIME_DIR=/run/user/$(id -u)
containerd-rootless-setuptool.sh install

Finch Works Correctly

Finch itself is fully functional:

$ finch --version
finch version v1.14.1

$ finch info
Client:
Namespace:     finch
Debug Mode:    false
Server:
Server Version: 1.7.28
Storage Driver: overlayfs
Logging Driver: json-file
Cgroup Driver: systemd
Cgroup Version: 2
...

$ finch ps
CONTAINER ID    IMAGE                                     COMMAND                   CREATED          STATUS    PORTS                     NAMES
6fa08d27c593    docker.io/amazon/dynamodb-local:latest    "java -jar DynamoDBL…"    51 seconds ago    Up        0.0.0.0:8000->8000/tcp    hotel-app-dynamodb-local

SAM CLI Detection Behavior

Debug Output from SAM CLI 1.151.0

2026-02-12 20:03:08,098 | ContainerClientFactory.create_client() called
2026-02-12 20:03:08,098 | Admin preference: None
2026-02-12 20:03:08,099 | Using auto-detected client creation
2026-02-12 20:03:08,099 | Trying Docker client creation
2026-02-12 20:03:08,099 | Creating Docker container client from environment variable.
2026-02-12 20:03:08,100 | Creating container client with parameters: {'version': '1.35'}
2026-02-12 20:03:08,100 | DockerContainerClient created successfully
2026-02-12 20:03:08,101 | Fall back docker api version to 1.44: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))
2026-02-12 20:03:08,103 | Docker daemon availability check failed with fallback: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))
2026-02-12 20:03:08,103 | Docker client not created, trying creating Finch client.
2026-02-12 20:03:08,103 | Creating Finch container client with base_url=unix:///var/run/finch.sock
2026-02-12 20:03:08,104 | Creating container client with parameters: {'base_url': 'unix:///var/run/finch.sock', 'version': '1.35'}
2026-02-12 20:03:08,104 | FinchContainerClient created successfully
2026-02-12 20:03:08,105 | Finch daemon availability check failed: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))
2026-02-12 20:03:08,106 | No container runtime available

Analysis

SAM CLI is looking for Finch at unix:///var/run/finch.sock, but on Linux with rootless containerd, the socket is at:

• $XDG_RUNTIME_DIR/containerd/containerd.sock (typically /run/user/1001/containerd/containerd.sock)

Additionally, the containerd socket uses a different API protocol than Docker's socket, so even when pointed to the correct location, SAM CLI's Docker Python library cannot communicate with it.

Workarounds Attempted (All Failed)

1. Environment Variables

export XDG_RUNTIME_DIR=/run/user/$(id -u)
export AWS_SAM_CONTAINER_RUNTIME=finch

Result: No effect on detection

2. SAM CLI Metadata File

mkdir -p ~/.aws-sam
cat > ~/.aws-sam/metadata.json <<EOF
{
  "container_runtime": "finch"
}
EOF

Result: File is read but ignored; SAM CLI still tries socket detection

3. Socket Symlink

sudo ln -sf /run/user/$(id -u)/containerd/containerd.sock /var/run/finch.sock

Result: Connection reset by peer (protocol incompatibility)

4. DOCKER_HOST Environment Variable

export DOCKER_HOST="unix:///run/user/$(id -u)/containerd/containerd.sock"

Result: SAM CLI still cannot communicate with containerd socket

5. Docker Command Symlink to Finch

sudo ln -sf $(which finch) /usr/local/bin/docker

Result: SAM CLI still tries socket connection before CLI commands

6. Docker Command Symlink to nerdctl

sudo ln -sf $(which nerdctl) /usr/local/bin/docker

Result: Same issue - socket detection happens first

Expected Behavior

According to the AWS SAM CLI documentation:

Starting with AWS SAM CLI version 1.145.0, AWS SAM CLI supports Finch as an alternative container runtime to Docker.

After you install Finch, the AWS SAM CLI automatically detects and uses Finch as a container runtime when Docker does not run.

SAM CLI should:

1. Detect that Finch is installed and available via the finch command
2. Use Finch's CLI interface instead of trying to connect to a socket
3. Fall back to using the finch command when socket detection fails

Root Cause

The SAM CLI Finch detection logic appears to be designed primarily for macOS, where Finch uses a VM with a Docker-compatible socket. On Linux:

1. Finch uses nerdctl + rootless containerd directly (no VM)
2. The containerd socket location is user-specific ($XDG_RUNTIME_DIR/containerd/containerd.sock)
3. The containerd socket uses a different API than Docker's socket
4. SAM CLI should fall back to using the finch CLI command, but this fallback never triggers

Proposed Solution

SAM CLI should:

1. Check for finch command availability before attempting socket connections
2. Use CLI-based container operations when the finch command is available, similar to how it would use the docker command
3. Support $XDG_RUNTIME_DIR for socket detection on Linux
4. Provide a --container-runtime flag to explicitly specify finch/docker (currently doesn't exist in 1.151.0 or 1.154.0)
5. Honor the AWS_SAM_CONTAINER_RUNTIME environment variable more reliably

Workaround for Users

Currently, the only reliable workaround is to install Docker, which defeats the purpose of using Finch.

Additional Context

• This issue affects workshop and tutorial environments where Docker cannot be installed
• Finch on Linux is officially supported as of October 2024
• The issue exists in both SAM CLI 1.151.0 and 1.154.0
• The --container-runtime flag mentioned in some documentation does not exist in these versions

Related Issues

• Feature request: support Finch for container related workflows #4584 - Original feature request for Finch support
• AWS Documentation: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-finch.html

[reedham-aws]

It seems like the PR pretty much covers the issue so I will keep further correspondence related to that in the PR itself (which I have not reviewed yet). I do have a few questions/comments about what you have in the description here:

1. You mention that the --container-runtime flag is mentioned in some documentation, would you mind linking that so I can take a look?
2. You mentioned that the docker-py SDK wouldn't work for rootless containerd

Additionally, the containerd socket uses a different API protocol than Docker's socket, so even when pointed to the correct location, SAM CLI's Docker Python library cannot communicate with it.

The PR seems to only look at the socket path and doesn't really get into this part; do you think there's more consideration to be made here? I'm not as familiar with the difference between the socket API protocols so this is something I'd need to look more into.
3. You mention that we should be using CLI based operations when the finch command is available. We are working on supporting BuildKit by allowing the CLI to be called directly when a parameter --use-buildkit is provided, meaning soon enough using the CLI instead of the SDK would be possible. In theory, this would be useful for number 2 above if that turns out to be a blocker.

[robbrad]

Thanks @reedham-aws

1/ I think I made a mistake on --container-runtime I could have sworn there was a SAM switch for it when I was using it a few years back. I might have been trying it in my debugging and kiro has picked it up

2/ The command detector for finch is working fine - so it's only the socket check that's an issue I believe

3/ Sound good !