AWS Lambda报Runtime.HandlerNotFound:lambda_handler缺失排查

一、Runtime.HandlerNotFound 报错根因与修复 #

这个报错和代码逻辑无关，是Lambda运行时的配置匹配问题：
Lambda Python运行时定位处理函数的规则为[部署代码文件名].[顶层函数名]，默认配置为lambda_function.lambda_handler，即要求部署包中存在lambda_function.py文件，且该文件顶层定义了名为lambda_handler、接收event、context两个参数的函数。
触发该报错的两种常见场景：

• 上传的代码文件名不是lambda_function.py（比如本地命名为user_db.py、test.py后直接打包上传）
• Lambda控制台「运行时设置-处理程序」字段配置值和实际文件名、函数名不匹配（Python大小写敏感，拼写错误也会触发）

修复操作：

1. 将代码文件重命名为lambda_function.py后重新打包部署
2. 检查Lambda运行时设置，确认处理程序配置为lambda_function.lambda_handler，无拼写、大小写错误

二、配置修复后仍触发Internal Server Error的代码问题 #

修正Handler配置后，当前代码仍存在4处会导致调用失败的问题：

• 类方法定义缺失参数：Create_table、Update_tabel两个方法未将self作为第一个入参，后续调用会触发参数不匹配错误；且Update_tabel存在拼写错误（正确为Update_table）
• 返回格式不符合API Gateway代理集成要求：如果通过API Gateway触发Lambda（Postman调用接口一般是这个场景），所有返回必须包含statusCode（数字类型）、body（字符串类型）字段，当前读表成功时直接返回DynamoDB的Item字典，不符合格式要求会直接触发500错误
• 缺少参数校验：代码未判断tasktype、data、user_name等必填字段是否存在，字段缺失时会直接抛出KeyError导致运行失败
• 异常捕获缺失：DynamoDB调用失败、参数格式错误等场景没有兜底处理，异常直接抛出会返回500

三、修复后的完整可运行代码 #

import boto3
import json

class userProfile:
    def __init__(self):
        dynamodb = boto3.resource('dynamodb')
        self.table = dynamodb.Table('user_data')

    def Create_table(self):
        pass

    def Read_table(self, event):
        try:
            response = self.table.get_item(
                Key={
                    'user_name': event['user_name']
                }
            )
        except Exception as e:
            return {
                'statusCode': 500,
                'body': json.dumps({'error': f'DynamoDB read failed: {str(e)}'})
            }

        if 'Item' in response:
            return {
                'statusCode': 200,
                'body': json.dumps(response['Item'], default=str)
            }
        else:
            return {
                'statusCode': 404,
                'body': json.dumps({'msg': f'User {event.get("user_name", "")} not found'})
            }

    def Update_table(self):
        pass


def lambda_handler(event, context):
    try:
        task_type = event.get('tasktype')
        if not task_type:
            return {
                'statusCode': 400,
                'body': json.dumps({'error': 'missing required field: tasktype'})
            }

        user_obj = userProfile()
        if task_type == "read":
            if 'data' not in event:
                return {
                    'statusCode': 400,
                    'body': json.dumps({'error': 'missing required field: data for read task'})
                }
            return user_obj.Read_table(event['data'])
        else:
            return {
                'statusCode': 400,
                'body': json.dumps({'error': f'unsupported tasktype: {task_type}'})
            }
    except Exception as e:
        return {
            'statusCode': 500,
            'body': json.dumps({'error': f'internal error: {str(e)}'})
        }

四、部署验证注意事项 #

• 给Lambda绑定的执行角色添加DynamoDB的dynamodb:GetItem权限，否则会触发权限拒绝错误
• 确认API Gateway和Lambda的集成开启了「Lambda代理集成」，否则返回格式不匹配仍会报错
• 测试读接口时传入的事件结构需符合预期，示例：

{
    "tasktype": "read",
    "data": {
        "user_name": "test_user_001"
    }
}

内容的提问来源于stack exchange，提问作者Anish R