SAM Doctor

Local AWS deployment diagnostics

Turn deployment noise into the next check.

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

Start in 60 seconds View source
  • 55documented diagnostics
  • Localanalysis by design
  • 0AWS credentials required
deployment.log local

$ sam-doctor diagnose deployment.log

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.
Matched line 41 Identifiers redacted

Built for the failure paths around

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.

  1. 01

    Give it the log.

    Point the CLI at a file, a sanitized excerpt, or stdin. The input stays on the machine running the command.

    sam-doctor diagnose deployment.log
  2. 02

    See what matched.

    Each finding includes the exact redacted evidence, a stable rule ID, and a confidence level.

    Evidence · line 41 · high
  3. 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
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 55 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.11.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.11.0 release notes
Install python -m pip install sam-doctor
Try it sam-doctor demo
Diagnose sam-doctor diagnose deployment.log --format markdown

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: Diagnose deployment log
  if: always()
  uses: jakegold1647/sam-doctor@v0
  with:
    log-file: deployment.log
    summary: true
    annotations: true
    fail-on-findings: true

Roll it out at your pace.

Use --fail-on-findings for shell-based CI, or keep the composite action advisory while your team measures signal quality.

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—not a claim of guaranteed root-cause analysis or a replacement for operator judgment.

Make the next failure easier

Bring the exact error that stopped your deploy.

Missing a signal, or seeing the wrong diagnosis? Share a short sanitized excerpt and help improve the next release.

Request a diagnostic rule Report a bad diagnosis

For deeper evaluation

See the team rollout guide, generate a reproducible packet with sam-doctor packet deployment.log, or read RESEARCHER_OVERVIEW.md.

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; you can then open a rule request with a short sanitized excerpt.

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.