Bug: SAM will not run with modern docker

[kenwdelong]

Description:

Running SAM fails, claiming it can't find docker: Error: Running AWS SAM projects locally requires Docker. Have you got it installed and running?

Steps to reproduce:

Run: sam local start-api --config-file samconfig-local.toml

Observed result:

$ sam local start-api --config-file samconfig-local.toml --debug 
2025-11-12 13:45:42,091 | Config file location:                                                     
/home/ken/work/workspace/ai-backend/samconfig-local.toml                                            
2025-11-12 13:45:42,093 | Loading configuration values from [default.['local',                      
'start-api'].parameters] (env.command_name.section) in config file at                               
'/home/ken/work/workspace/ai-backend/samconfig-local.toml'...                                       
2025-11-12 13:45:42,094 | Configuration values successfully loaded.                                 
2025-11-12 13:45:42,094 | Configuration values are: {'parameter_overrides': ['PhoenixEnabled=true', 
'StageName=local', 'PhoenixEndpoint=http://172.17.0.1:6006/v1/traces'], 'env_vars': 'env.json'}     
2025-11-12 13:45:42,109 | Using SAM Template at                                                     
/home/ken/work/workspace/ai-backend/.aws-sam/build/template.yaml                                    
2025-11-12 13:45:42,126 | Using config file: samconfig-local.toml, config environment: default      
2025-11-12 13:45:42,127 | Expand command line arguments to:                                         
2025-11-12 13:45:42,127 |                                                                           
--template_file=/home/ken/work/workspace/ai-backend/.aws-sam/build/template.yaml --host=127.0.0.1   
--port=3000 --static_dir=public --env_vars=env.json --parameter_overrides={'PhoenixEnabled': 'true',
'StageName': 'local', 'PhoenixEndpoint': 'http://172.17.0.1:6006/v1/traces'}                        
--layer_cache_basedir=/home/ken/.aws-sam/layers-pkg --container_host=localhost                      
--container_host_interface=127.0.0.1                                                                
2025-11-12 13:45:42,211 | local start-api command is called                                         
2025-11-12 13:45:42,699 | Collected default values for parameters: {'StageName': 'qa',              
'HatchApiHostName': 'https://qa-data.hatchbaby.com', 'ApiDomainName': '', 'ApiCertificateArn': '',  
'HostedZoneName': '', 'ApiBasePath': '', 'EndpointType': 'REGIONAL', 'OpenAiApiKey': '',            
'OpenAiAssistantId': '', 'BedrockModelId': 'us.anthropic.claude-3-5-haiku-20241022-v1:0',           
'BedrockModelTemperature': '0.3', 'BedrockModelMaxTokens': '512', 'MessageHistoryLimit': '10',      
'PhoenixEnabled': 'false', 'PhoenixEndpoint': 'http://host.docker.internal:6006/v1/traces', 'VpcId':
'', 'SubnetIds': '', 'SecurityGroupIds': '', 'DdbTableName': 'ai-backend-qa-message-history'}       
2025-11-12 13:45:42,719 | There is no customer defined id or cdk path defined for resource          
LoggingLayer, so we will use the resource logical id as the resource id                             
2025-11-12 13:45:42,720 | There is no customer defined id or cdk path defined for resource          
CommonLayer, so we will use the resource logical id as the resource id                              
2025-11-12 13:45:42,720 | Sam customer defined id is more priority than other IDs. Customer defined 
id for resource AskFunction is AskFunction                                                          
2025-11-12 13:45:42,721 | There is no customer defined id or cdk path defined for resource          
ServerlessRestApi, so we will use the resource logical id as the resource id                        
2025-11-12 13:45:42,722 | Unable to resolve property VpcConfig: OrderedDict([('Fn::If', ['UseVpc',  
OrderedDict([('SecurityGroupIds', OrderedDict([('Ref', 'SecurityGroupIds')])), ('SubnetIds',        
OrderedDict([('Ref', 'SubnetIds')]))]), OrderedDict([('Ref', 'AWS::NoValue')])])]). Leaving as is.  
2025-11-12 13:45:42,724 | 0 stacks found in the template                                            
2025-11-12 13:45:42,725 | Collected default values for parameters: {'StageName': 'qa',              
'HatchApiHostName': 'https://qa-data.hatchbaby.com', 'ApiDomainName': '', 'ApiCertificateArn': '',  
'HostedZoneName': '', 'ApiBasePath': '', 'EndpointType': 'REGIONAL', 'OpenAiApiKey': '',            
'OpenAiAssistantId': '', 'BedrockModelId': 'us.anthropic.claude-3-5-haiku-20241022-v1:0',           
'BedrockModelTemperature': '0.3', 'BedrockModelMaxTokens': '512', 'MessageHistoryLimit': '10',      
'PhoenixEnabled': 'false', 'PhoenixEndpoint': 'http://host.docker.internal:6006/v1/traces', 'VpcId':
'', 'SubnetIds': '', 'SecurityGroupIds': '', 'DdbTableName': 'ai-backend-qa-message-history'}       
2025-11-12 13:45:42,741 | There is no customer defined id or cdk path defined for resource          
LoggingLayer, so we will use the resource logical id as the resource id                             
2025-11-12 13:45:42,742 | There is no customer defined id or cdk path defined for resource          
CommonLayer, so we will use the resource logical id as the resource id                              
2025-11-12 13:45:42,742 | Sam customer defined id is more priority than other IDs. Customer defined 
id for resource AskFunction is AskFunction                                                          
2025-11-12 13:45:42,743 | There is no customer defined id or cdk path defined for resource          
ServerlessRestApi, so we will use the resource logical id as the resource id                        
2025-11-12 13:45:42,744 | Unable to resolve property VpcConfig: OrderedDict([('Fn::If', ['UseVpc',  
OrderedDict([('SecurityGroupIds', OrderedDict([('Ref', 'SecurityGroupIds')])), ('SubnetIds',        
OrderedDict([('Ref', 'SubnetIds')]))]), OrderedDict([('Ref', 'AWS::NoValue')])])]). Leaving as is.  
2025-11-12 13:45:42,745 | 4 resources found in the stack                                            
2025-11-12 13:45:42,746 | --base-dir is not presented, adjusting uri ../../layers/logging relative  
to /home/ken/work/workspace/ai-backend/.aws-sam/build/template.yaml                                 
2025-11-12 13:45:42,746 | --base-dir is not presented, adjusting uri ../../layers/common relative to
/home/ken/work/workspace/ai-backend/.aws-sam/build/template.yaml                                    
2025-11-12 13:45:42,747 | Found Serverless function with name='AskFunction' and                     
CodeUri='AskFunction'                                                                               
2025-11-12 13:45:42,747 | --base-dir is not presented, adjusting uri AskFunction relative to        
/home/ken/work/workspace/ai-backend/.aws-sam/build/template.yaml                                    
2025-11-12 13:45:42,750 | Docker is not reachable                                                   
Traceback (most recent call last):                                                                  
  File "docker/api/client.py", line 275, in _raise_for_status                                       
  File "requests/models.py", line 1026, in raise_for_status                                         
requests.exceptions.HTTPError: 400 Client Error: Bad Request for url:                               
http+docker://localhost/v1.35/_ping                                                                 
                                                                                                    
The above exception was the direct cause of the following exception:                                
                                                                                                    
Traceback (most recent call last):                                                                  
  File "samcli/local/docker/utils.py", line 88, in is_docker_reachable                              
  File "docker/client.py", line 201, in ping                                                        
  File "docker/api/daemon.py", line 166, in ping                                                    
  File "docker/api/client.py", line 281, in _result                                                 
  File "docker/api/client.py", line 277, in _raise_for_status                                       
  File "docker/errors.py", line 39, in create_api_error_from_http_exception                         
docker.errors.APIError: 400 Client Error for http+docker://localhost/v1.35/_ping: Bad Request       
("client version 1.35 is too old. Minimum supported API version is 1.44, please upgrade your client 
to a newer version")                                                                                
2025-11-12 13:45:42,752 | Telemetry endpoint configured to be                                       
https://aws-serverless-tools-telemetry.us-west-2.amazonaws.com/metrics                              
2025-11-12 13:45:42,759 | Telemetry endpoint configured to be                                       
https://aws-serverless-tools-telemetry.us-west-2.amazonaws.com/metrics                              
2025-11-12 13:45:42,759 | Sending Telemetry: {'metrics': [{'commandRun': {'requestId':              
'd4617b22-c316-4f36-8611-f646672947e8', 'installationId': 'ad93cfa5-d9df-4271-9755-3ce6104c84ae',   
'sessionId': 'dfbfa00f-81c2-4218-87e0-6098bdf8d3a2', 'executionEnvironment': 'CLI', 'ci': False,    
'pyversion': '3.11.10', 'samcliVersion': '1.144.0', 'awsProfileProvided': False,                    
'debugFlagProvided': True, 'region': '', 'commandName': 'sam local start-api',                      
'metricSpecificAttributes': {'projectType': 'CFN', 'gitOrigin': None, 'projectName':                
'352291a5e8a94b968c9e96a24c6b941e760b5f62a6f5ea8e722ea43ce4708e04', 'initialCommit': None,          
'containerEngine': 'docker-default'}, 'duration': 626, 'exitReason':                                
'DockerIsNotReachableException', 'exitCode': 1}}]}                                                  
2025-11-12 13:45:42,760 | Unable to find Click Context for getting session_id.                      
2025-11-12 13:45:42,763 | Sending Telemetry: {'metrics': [{'events': {'requestId':                  
'95387d8b-73b3-464f-b144-d0be2e522aa9', 'installationId': 'ad93cfa5-d9df-4271-9755-3ce6104c84ae',   
'sessionId': 'dfbfa00f-81c2-4218-87e0-6098bdf8d3a2', 'executionEnvironment': 'CLI', 'ci': False,    
'pyversion': '3.11.10', 'samcliVersion': '1.144.0', 'commandName': 'sam local start-api',           
'metricSpecificAttributes': {'events': [{'event_name': 'SamConfigFileExtension', 'event_value':     
'.toml', 'thread_id': '554c305a178643cc9501ccf4f12fd5e6', 'time_stamp': '2025-11-12 20:45:42.091',  
'exception_name': None}, {'event_name': 'SamConfigFileExtension', 'event_value': '.toml',           
'thread_id': '54a2cb5e44dc479e93882bf0ab6333df', 'time_stamp': '2025-11-12 20:45:42.126',           
'exception_name': None}], 'containerEngine': 'docker-default'}}}]}                                  
2025-11-12 13:45:43,074 |                                                                           
HTTPSConnectionPool(host='aws-serverless-tools-telemetry.us-west-2.amazonaws.com', port=443): Read  
timed out. (read timeout=0.1)                                                                       
2025-11-12 13:45:43,081 |                                                                           
HTTPSConnectionPool(host='aws-serverless-tools-telemetry.us-west-2.amazonaws.com', port=443): Read  
timed out. (read timeout=0.1)                                                                       
Error: Running AWS SAM projects locally requires Docker. Have you got it installed and running?

Expected result:

To work correctly: start the docker container

Additional environment details (Ex: Windows, Mac, Amazon Linux etc)

1. OS: POP_os (Ubuntu)
2. sam --version: SAM CLI, version 1.144.0
3. AWS region: us-west-2

sam --info
{
  "version": "1.144.0",
  "system": {
    "python": "3.11.10",
    "os": "Linux-6.17.4-76061704-generic-x86_64-with-glibc2.35"
  },
  "additional_dependencies": {
    "docker_engine": "Not available",
    "aws_cdk": "Not available",
    "terraform": "Not available"
  },
  "available_beta_feature_env_vars": [
    "SAM_CLI_BETA_FEATURES",
    "SAM_CLI_BETA_BUILD_PERFORMANCE",
    "SAM_CLI_BETA_TERRAFORM_SUPPORT",
    "SAM_CLI_BETA_PACKAGE_PERFORMANCE",
    "SAM_CLI_BETA_RUST_CARGO_LAMBDA"
  ]
}

Add --debug flag to command you are running

[kenwdelong]

Oh, this looks related: testcontainers/testcontainers-java#11212

[JacobSteelsmith]

On Ubuntu 22.04.5 one workaround that worked for me is to downgrade Docker:

sudo service docker stop

sudo apt remove docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

VERSION_STRING=5:28.5.2-1~ubuntu.22.04~jammy

sudo apt-get install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin

[HagerError404]

+1 with 1.146.0.
Still trying to use old 1.35.0 client

2025-11-18 16:12:09,982 | Container daemon availability check failed: 400 Client Error for https://localhost:2376/v1.35/_ping: Bad Request ("client version 1.35 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer 
version")                                                                                                                                                                                                                                                 
2025-11-18 16:12:09,983 | Docker client not created, trying creating Finch client.                                                                                                                                                                        
2025-11-18 16:12:09,984 | Creating Finch container client with base_url=unix:///var/run/finch.sock                                                                                                                                                        
2025-11-18 16:12:09,985 | Creating container client with parameters: {'base_url': 'unix:///var/run/finch.sock', 'tls': <docker.tls.TLSConfig object at 0x7f5623334e10>, 'version': '1.35'}                                                                
2025-11-18 16:12:09,986 | FinchContainerClient created successfully                                                                                                                           ```                                             

[stevesirois]

The next release will solve this, see this PR

[shenanigami]

Hi y'all 👋 Thanks for the fix!

I have a question regarding this topic, specifically about the following PR, which is related and builds on top of the one Steve linked earlier. @roger-zhangg would the fallback mechanism ever fail (as well)? I was thinking it would be nice to have something, like

import os

DOCKER_MIN_API_VERSION = "1.35"
DOCKER_MIN_API_VERSION_FALLBACK = os.environ.get("SAM_DOCKER_API_VERSION", "1.44")

for the constants.py. In case fallback fails too, and the user would have the option to export min api version without editing the codebase, and while waiting for the fix in the next release.

[roger-zhangg]

Hi @shenanigami , Thanks for the suggestion! While I'll implement this as a fallback option, I believe it would be more efficient to add environment parsing for DOCKER_MIN_API_VERSION direct. When this variable is detected, it essentially indicates that both the default & fallback mechanism isn't functioning as intended.

In the mean time, please checkout the new release: https://github.com/aws/aws-sam-cli/releases/tag/v1.147.1

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.