SAM Doctor

ERROR REFERENCE

CodeBuild cannot use the configured CodeConnections connection

CloudFormation reached CodeBuild, but the project could not use the source connection while it was being created. This is usually a CodeBuild project-role or connection-readiness problem, not a reason to widen the role that launched the deployment.

WHAT IT MEANS

What this error means

User is not authorized to access connection [REDACTED_ARN]
(Service: AWSCodeBuild; Status Code: 400; Error Code: OAuthProviderException)

The CodeBuild resource handler rejected the configured CodeConnections source connection. The project service role may not be allowed to read the connection token, the connection may not be available in the target account or Region, or a policy attached in the same stack may not have propagated before project creation.

FIX

How to fix it

  1. Find the two identities and the connection: record the CodeBuild project's service role, the connection ARN, and the account and Region used by the deployment. Do not inspect only the role that runs sam deploy.
  2. Read the CodeBuild role policies (read-only): 
    aws iam list-role-policies --role-name <codebuild-role>
aws iam list-attached-role-policies --role-name <codebuild-role>
    For a CodeConnections source, check the policy for codeconnections:GetConnection and codeconnections:GetConnectionToken. Some service paths also require codeconnections:UseConnection scoped to the connection.
  3. Check the connection itself (read-only): 
    aws codeconnections get-connection --connection-arn <connection-arn>
    Confirm that it is available, belongs to the target account (or is intentionally shared), and uses the provider expected by the CodeBuild source configuration.
  4. Fix stack ordering when the role is created with the project. Make the CodeBuild project depend on the role policy attachment, then retry after IAM propagation. A policy on the deployment role cannot replace permissions on the project role.

See the AWS guides for the CodeBuild GitHub App connection flow and the CodeConnections action reference.

AUTOMATE THE TRIAGE

Diagnose this automatically

SAM Doctor recognizes the AWSCodeBuild OAuthProviderException (high confidence), keeps it separate from generic CloudFormation resource failures, and shows the project-role and connection checks. Runs locally; no AWS access, no log upload. 

python -m pip install sam-doctor
sam-doctor diagnose deployment.log --format markdown

RELATED