Textract start_document_text_detection任务卡在IN_PROGRESS状态如何排查

问题场景 #

调用Textract异步文本检测接口start_document_text_detection提交任务后，任务长期停留在IN_PROGRESS状态，配置的SNS主题收不到任务完成推送，调用代码如下：

s3client = boto.client('s3', region_name=REGION_NAME)
textract = boto.client('textract', region_name=REGION_NAME)
response = textract.start_document_text_detection(
    DocumentLocation={
        'S3Object': {'Bucket': 'bucket', 'Name':'name'}
    },
    NotificationChannel={
        'SNSTopicArn': 'arn', 'RoleArn': 'role'        
    },
    OutputConfig={
        'S3Bucket': 'bucket',
        'S3Prefix': 'prefix'
    }
)

通过接口返回的JobId调用get_document_text_detection轮询状态，始终返回IN_PROGRESS，无失败报错。

核心故障原因（按出现概率排序） #

• IAM角色权限配置错误：这是该类问题最高发的诱因。NotificationChannel中传入的RoleArn对应角色存在两类配置问题：一是角色信任策略未允许textract.amazonaws.com服务代入角色，二是角色未绑定sns:Publish到目标SNS主题、S3对应资源读写的权限。权限缺失时Textract既无法完成状态回调，也无法投递SNS通知，任务会直接卡住。
• SNS主题访问策略拦截：SNS主题默认访问策略仅允许账户内授权用户/角色发布消息，不会自动放通AWS服务的发布请求。哪怕IAM角色已经配置了SNS发布权限，只要主题资源策略没有显式放通Textract的发布权限，消息就会被拦截，通知链路断连后任务状态无法正常流转。
• S3资源权限缺失：存储源文件的S3桶未给Textract授予s3:GetObject权限，或者配置的输出S3桶未给Textract授予s3:PutObject权限，任务会卡在读取源文件、写入结果的环节。如果S3桶使用自定义KMS密钥做服务端加密，还需要额外给Textract授予对应KMS密钥的加解密权限，缺项同样会导致任务卡住。
• 资源跨区域不匹配：Textract异步任务要求所有关联资源（输入S3桶、输出S3桶、SNS主题）必须和初始化Textract客户端时指定的区域完全一致，跨区域部署资源时，接口不会直接抛出参数错误，任务会长期停留在IN_PROGRESS状态。
• 源文件不符合规范：Textract异步检测仅支持PDF、TIFF、JPEG、PNG格式文件，单文件大小上限为500MB。如果传入的是不支持的格式、文件损坏、大小超限，部分场景下不会直接标记任务失败，会长期停留在处理中状态。
• SSE-C加密不兼容：如果输入/输出S3桶开启了SSE-C（用户自持密钥的服务端加密），Textract不支持访问该类加密对象，任务会卡住且无明确报错返回。

快速排查步骤 #

1. 先核对所有关联资源的所属区域，确保和Textract客户端配置的region_name完全一致，跨区配置是最容易忽略的低级错误。
2. 检查目标IAM角色的信任策略，确认信任主体包含textract.amazonaws.com，同时核对角色绑定的权限策略，覆盖S3对应路径读写、SNS主题发布、KMS密钥加解密（如果用了自定义密钥）的必要权限。
3. 检查SNS主题的资源策略，显式添加放通Textract通过上述IAM角色发布消息的策略语句。
4. 临时去掉NotificationChannel和OutputConfig参数，用一个1MB以内、格式正常的JPG/PNG测试文件提交任务：如果测试任务能正常完成，说明问题出在SNS通知链路或输出S3的配置上；如果测试任务依然卡住，优先排查输入S3的权限、加密配置和源文件合规性。
5. 确认源文件格式、大小符合Textract要求，没有损坏，且S3桶没有开启SSE-C加密。

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