# SAM Doctor

> SAM Doctor is a local, evidence-first CLI and GitHub Action for diagnosing supported AWS SAM, CloudFormation, IAM, and GitHub Actions deployment failures. It reads text locally, redacts common identifiers, and returns evidence, confidence, safe verification steps, and official documentation.

SAM Doctor does not access AWS, upload logs, change resources, or claim an authoritative root cause.

## Start here

- [Project homepage](https://sam-doctor.jacobgoldstein.dev/): install, demo, supported categories, and GitHub Actions usage.
- [PyPI package](https://pypi.org/project/sam-doctor/): install the stable CLI with `python -m pip install sam-doctor`.
- [GitHub repository](https://github.com/jakegold1647/sam-doctor): source, tests, issues, and contribution guide.
- [GitHub Marketplace Action](https://github.com/marketplace/actions/sam-doctor-aws-deployment-diagnostics): diagnose saved deployment logs in CI.

## Exact-error guides

- [Deployment error index](https://sam-doctor.jacobgoldstein.dev/errors/): one page per exact error string with causes, fixes, and the diagnose command.
- [Not authorized to perform: sts:AssumeRoleWithWebIdentity](https://sam-doctor.jacobgoldstein.dev/errors/assume-role-with-web-identity.html): GitHub Actions OIDC trust-policy rejection.
- [Stack is in ROLLBACK_COMPLETE state and can not be updated](https://sam-doctor.jacobgoldstein.dev/errors/rollback-complete-cannot-be-updated.html): recover from a failed initial stack create.
- [InsufficientCapabilitiesException](https://sam-doctor.jacobgoldstein.dev/errors/insufficient-capabilities.html): when to pass CAPABILITY_IAM, CAPABILITY_NAMED_IAM, or CAPABILITY_AUTO_EXPAND.
- [The security token included in the request is expired](https://sam-doctor.jacobgoldstein.dev/errors/expired-token.html): expired sessions, OIDC session duration, and clock skew.
- [no basic auth credentials](https://sam-doctor.jacobgoldstein.dev/errors/no-basic-auth-credentials.html): unauthenticated Docker push to Amazon ECR.
- [An error occurred (Throttling): Rate exceeded](https://sam-doctor.jacobgoldstein.dev/errors/rate-exceeded.html): CloudFormation API rate limits from CI fan-out.
- [DELETE_FAILED](https://sam-doctor.jacobgoldstein.dev/errors/delete-failed.html): blocked stack deletion and --retain-resources.
- [Cannot connect to the Docker daemon](https://sam-doctor.jacobgoldstein.dev/errors/docker-unavailable.html): sam build --use-container without a reachable Docker daemon.
- [Esbuild Failed: Cannot find esbuild](https://sam-doctor.jacobgoldstein.dev/errors/esbuild-not-found.html): missing esbuild devDependency in the function project.
- [The REST API doesn't contain any methods](https://sam-doctor.jacobgoldstein.dev/errors/rest-api-no-methods.html): API Gateway deployment/method ordering.
- [No changes to deploy / No updates are to be performed](https://sam-doctor.jacobgoldstein.dev/errors/no-changes-to-deploy.html): the empty change set and --no-fail-on-empty-changeset.
- [Access denied with an explicit deny](https://sam-doctor.jacobgoldstein.dev/errors/access-denied-explicit-deny.html): SCP and Deny-statement failures that Allow policies cannot fix.
- [Denied because no policy allows it](https://sam-doctor.jacobgoldstein.dev/errors/access-denied-no-policy-allows.html): implicit denies and the policy layer the error names.
- [Resource did not stabilize (NotStabilized)](https://sam-doctor.jacobgoldstein.dev/errors/resource-did-not-stabilize.html): nested handler messages, slow resources, and stuck custom handlers.
- [Export cannot be updated as it is in use](https://sam-doctor.jacobgoldstein.dev/errors/export-in-use.html): cross-stack import pins and staged export migration.
- [GitHub Actions integration](https://github.com/jakegold1647/sam-doctor/blob/main/docs/github-actions-integration.md): add SAM Doctor after an existing AWS SAM deployment command without changing its AWS authentication model.
- [AssumeRoleWithWebIdentity / GitHub Actions OIDC](https://github.com/jakegold1647/sam-doctor/blob/main/docs/oidc-deployment-debugging.md): check `id-token: write`, the STS audience, and the trust-policy subject.
- [CloudFormation ROLLBACK_COMPLETE](https://github.com/jakegold1647/sam-doctor/blob/main/docs/cloudformation-first-failure.md): find the first failed resource event instead of treating rollback as the root cause.
- [InsufficientCapabilitiesException](https://github.com/jakegold1647/sam-doctor/blob/main/docs/capability-acknowledgement.md): review IAM resources and acknowledge `CAPABILITY_IAM` or `CAPABILITY_NAMED_IAM` deliberately.

## Supported signals

- GitHub Actions OIDC token, audience, subject, and `AssumeRoleWithWebIdentity` failures.
- IAM `AccessDenied` errors and IAM trust-policy shape errors.
- CloudFormation failed resources, rollback states, and capability acknowledgements.
- AWS SAM configuration, change-set, packaging, S3 artifact, esbuild, and Python dependency/runtime build failures.
- API Gateway deployment and CORS preflight conflicts.
- Lambda container-image failures caused by missing ECR image access.

## Safe usage

1. Save the smallest sanitized error excerpt you are authorized to inspect.
2. Run `sam-doctor diagnose deployment.log` or `sam-doctor demo`.
3. Treat the finding as a focused starting point; verify it against AWS or GitHub documentation before changing anything.
4. Never share account IDs, ARNs, credentials, tokens, customer data, or complete production logs.