Local AWS deployment diagnostics

Turn deployment noise into the next check.

SAM Doctor reads a failed deployment log, finds supported AWS failure patterns, then returns the evidence, confidence, and safest next step. It works without AWS credentials or a log upload.

Start in 60 seconds View source

96documented diagnostics
Localanalysis by design
0AWS credentials required

deployment.log local

$ sam-doctor diagnose deployment.log --format markdown

Finding 01 high confidence

GitHub Actions cannot assume the configured AWS role through OIDC.

Evidence: Not authorized to perform: sts:AssumeRoleWithWebIdentity
Check next: Verify id-token: write, then review the audience and subject conditions.

Built for the failure paths around

AWS SAM
CloudFormation
IAM
GitHub Actions
CDK logs

A smaller incident loop

One command between the failure and the fix.

Keep the original deployment flow. Add a deterministic first pass before changing IAM, templates, or CI configuration.

01
Capture the failure.

Wrap the deploy or point the CLI at a file, a sanitized excerpt, or stdin. The input stays on the machine running the command.
sam-doctor run --log-file deployment.log -- sam deploy
02
See what matched.

Each finding includes the exact redacted evidence, a stable rule ID, and a confidence level.
Evidence · line 41 · high
03
Verify before changing.

Use the focused next check and linked source material. SAM Doctor never applies a remediation for you.
Next · inspect trust policy

Evidence over guesses

A useful answer, not another wall of logs.

SAM Doctor ranks supported signals, keeps excerpts short, and tells you where the match came from. The output is designed to drop into an issue, incident thread, or pull request without exposing an entire production log.

Evidence and source line for every finding
Common account IDs, ARNs, and tokens redacted
Markdown, JSON, SARIF, and GitHub annotation output
Stable rule IDs for CI and code-scanning workflows

See worked incident examples Browse sanitized, tracked examples Use an opt-in PR comment workflow (forks keep summaries)

Shareable report · Markdown

Likely cause · high confidence

OIDC trust conditions reject this workflow identity.

Evidence
Not authorized to perform: sts:AssumeRoleWithWebIdentity

Verify
Confirm the workflow can mint an ID token, then compare its audience and subject to the role trust policy.

1 finding · 1 next check · 0 secrets

Failure coverage

Start with the errors that stall deploys.

Browse all 96 error guides

Identity

OIDC & role assumption

Token permissions, trust-policy audience and subject mismatches, missing providers, and expired sessions.

Open guide Stacks

Rollback & lifecycle states

Find the first failed resource beneath ROLLBACK_COMPLETE, DELETE_FAILED, and nested-stack noise.

Open guide Permissions

IAM access decisions

Separate explicit denies from missing allows, then identify the principal, action, and policy layer.

Open guide Build

Packaging & containers

Docker availability, registry pulls, esbuild, Python runtimes, dependency resolution, and artifact uploads.

Open guide

Get started

Install v0.14.0 in one command.

Python 3.10 or newer. Run the built-in demo first, or point SAM Doctor straight at a failed deployment log.

View on PyPI View v0.14.0 release notes

Install python -m pip install sam-doctor

Try it sam-doctor demo

Diagnose sam-doctor diagnose deployment.log --format markdown

Update python -m pip install --upgrade sam-doctor

Stable PyPI includes all 96 documented diagnostics, plus the shell-independent run wrapper and clipboard handoff. The standard install command is all you need.

Close to the failure

Add the same first pass to CI.

Run after the deployment step with if: always(). Start non-blocking, then opt into confidence-based or strict gating after the signal is proven.

- name: Deploy and diagnose
  id: sam-doctor
  uses: jakegold1647/sam-doctor@v0
  with:
    log-file: deployment.log
    run-command: sam deploy --no-confirm-changeset
    summary: true
    annotations: true
    # fail-on-findings: true

Roll it out at your pace.

Keep the Action advisory while your team measures signal quality, then add --fail-on-findings or a confidence gate when the evidence is stable. The @v0 tag follows stable releases; pin a specific release tag when reproducibility requires it.

Download the sam-doctor GitHub Actions starter

More deployment and CI starters

Choose by command in the CI command matrix, or browse examples/README.md.

Useful boundaries

Private by default. Deliberately not magic.

Your log stays local.

No cloud service, account connection, telemetry requirement, or raw-log upload.

Nothing changes automatically.

No policy edits, stack updates, resource deletes, or remediation commands are run for you.

Every answer remains reviewable.

A finding is a focused starting point. It is not a claim of guaranteed root-cause analysis or a replacement for operator judgment.

Contribute a first improvement

Make the next failure easier.

Start with a small, mentored contributor issue or share a usage result when a diagnosis helps, misses, or leaves you unsure what to do next. Draft PRs are welcome if you want feedback before the change is finished. Want to discuss an idea or show what you built? Those paths are welcome too. If a report is wrong, tell us what you expected.

Browse mentored first issues Ask in the welcome discussion Request a diagnostic rule

For deeper evaluation

Choose a checked-in starter from the public CI recipe index, see the team rollout guide, generate a reproducible packet with sam-doctor packet deployment.log, read RESEARCHER_OVERVIEW.md, or meet the community in the contributor hall of fame.

Common questions

Before you put it in the pipeline.

Does SAM Doctor need AWS access?

No. It reads only the text you provide and does not make AWS API calls.

What if no supported pattern matches?

It reports no supported finding. That is safer than inventing a cause; run sam-doctor request-packet deployment.log to write a short sanitized excerpt, review it, then open a rule request.

Can it fail a CI job?

Yes, but only when you opt in. Start advisory, gate high-confidence findings when ready, then use strict gating if it fits your workflow.