LOCAL AWS DEPLOYMENT DIAGNOSTICS

Debug AWS SAM, CloudFormation, and GitHub Actions deployment failures.

SAM Doctor reads a deployment log on your machine, identifies supported SAM, CloudFormation, IAM, and GitHub Actions OIDC failure patterns, and produces evidence, safe checks, and a shareable Markdown report.

Try the free tool Help shape the next version

Runs locally. No AWS credentials. No log upload. No automatic changes.

Read the OIDC deployment debugging guide | Find the first useful CloudFormation failure | Fix InsufficientCapabilities

GET STARTED

Install v0.7.7 in one command.

python -m pip install sam-doctor

This installs the latest stable release from PyPI. Then run sam-doctor demo to see a local example, or pass a log to sam-doctor diagnose deployment.log.

View on PyPI View v0.7.7 release notes

$ sam-doctor diagnose failed-deploy.log --format markdown

Likely cause - high confidence

GitHub Actions cannot assume the configured AWS role through OIDC.

Evidence: Not authorized to perform: sts:AssumeRoleWithWebIdentity

Next: verify id-token: write, the OIDC audience, and the trust policy subject condition.

GITHUB ACTIONS

Keep the diagnostic close to the failed workflow.

- name: Deploy
  shell: bash
  run: |
    set -o pipefail
    sam deploy --no-confirm-changeset 2>&1 | tee deployment.log

- name: Diagnose deployment log
  if: always()
  id: sam-doctor
  uses: jakegold1647/sam-doctor@v0.7.7
  with:
    log-file: deployment.log
    summary: "true"
    # fail-on-findings: "true"

Put the action after the command that writes the log and keep if: always(), or GitHub skips it when deployment fails. It exposes finding-count and has-findings outputs; job summaries and failure gating are opt-in. Uncomment fail-on-findings: "true" when a supported diagnosis should fail the job.

For shell-based CI, run sam-doctor diagnose deployment.log --format json --output diagnosis.json --fail-on-findings. It writes the report and returns status 1 only when a supported finding is present.

Use from GitHub Marketplace

WHAT IT HANDLES NOW

Start with the failures that waste deployment time.

GitHub Actions OIDC and role-assumption failures
GitHub Actions job summaries and opt-in CI gating
IAM access-denied errors
CloudFormation rollback states
CloudFormation capability acknowledgement errors
Template, IAM trust-policy, and deployment-artifact errors
SAM configuration and change-set failures
API Gateway CORS preflight conflicts

WHAT IT DOES NOT DO

Useful without pretending to be magic.

No AWS account access or automatic remediation
No claim of guaranteed root-cause analysis
No replacement for a security review or production operator
No raw-log upload or cloud processing

A SMALL, USEFUL LOOP

From noisy log to next check.

Give it a log. Point the CLI at a file or pipe text through stdin.
See the evidence. Matching lines are redacted and kept short.
Verify the cause. Use the linked docs and review every suggested change.

SHAPE THE NEXT VERSION

Tell me the exact error that stopped your deploy.

SAM Doctor is a free tool. The next version will focus on the failures that repeatedly waste real developers' time - starting with GitHub Actions to AWS OIDC role-assumption failures. Share a sanitized error or request an improvement in GitHub Issues.

Share deployment feedback

Please remove account IDs, ARNs, tokens, and customer data before posting.

Common AWS deployment questions

What does SAM Doctor diagnose?

It recognizes explicit AWS SAM, CloudFormation, IAM, API Gateway, and GitHub Actions deployment failure patterns, including AssumeRoleWithWebIdentity, InsufficientCapabilitiesException, rollback states, and ECR image access failures.

Does SAM Doctor access AWS or upload logs?

No. The CLI and core diagnostic logic process the text locally. They do not call AWS, upload logs, change resources, or make an automatic fix.

What should I do with a CloudFormation ROLLBACK_COMPLETE error?

Find the earliest related CREATE_FAILED or UPDATE_FAILED resource event first. Run the sanitized status reason through SAM Doctor, then verify the underlying service cause before retrying.

Can SAM Doctor prove the root cause?

No. It reports only what a matched text pattern supports and labels confidence. Use its safe checks and official documentation to confirm the diagnosis before changing a policy or stack.