content(what-is): rewrite the Unable to locate credentials page

[alexleventer]

Summary

Rewrites content/what-is/resolve-unable-to-locate-credentials.md for SEO and AEO. The page now leads with a direct answer that names the actual root cause (empty credential chain) and walks through each source the SDK checks.

What changed

• Opening direct answer — bold one-paragraph definition: the credential provider chain ran to completion and every source returned empty.
• "In this article, we'll cover" lead-in for navigability.
• Credential provider chain section — numbered list of the five sources the SDK checks in order, so readers know where to look.
• Causes table — seven common gaps mapped to symptom and fix, including the EC2 IMDSv2 hop-limit-in-Docker case.
• Numbered fix steps — inspect what SDK sees, configure a source, attach a role for servers, verify with get-caller-identity.
• Prevention section — one source per environment, sudo -E caveat, OIDC for CI, document expected creds in README.
• Pulumi ESC section — YAML environment example plus esc run; brief reference to aws:assumeRole for in-program use.
• Related errors cross-links — sibling resolve-* pages, with one-line distinctions so readers can self-route.
• FAQ — six doubt-removers: profile vs default, cron/systemd, EC2 metadata reachability, SDK naming differences, region-vs-credentials, why static keys are wrong for servers.
• Strengthened meta_desc to lead with the direct answer, well under 160 chars.

Test plan

• make serve; visit /what-is/resolve-unable-to-locate-credentials/ and confirm the page renders with tables, code blocks, and cross-links intact.
• Spot-check links to sibling resolve-* pages and to /docs/pulumi-cloud/esc/ and /docs/esc/environments/configuring-oidc/aws/.
• CI lint + pinned review.

🤖 Generated with Claude Code

[github-actions]

Pre-merge Review — Last updated 2026-05-20T16:52:18Z

Tip

Summary: This PR rewrites the existing what-is/resolve-unable-to-locate-credentials page, paralleling the sibling resolve-list-buckets-* error-explainer pages under content/what-is/. The risk to a reader's success is mis-ordering the AWS credential provider chain (so they probe the wrong source first) or over-promising about Pulumi AWS-provider assumeRole behavior (so they expect a pulumi up to "just work" without base credentials). Claim extraction (28 candidates), four-specialist external verification, and a frontmatter sweep ran; Hugo build, code execution, and editorial-balance passes were skipped per the routing.

Review confidence:

Dimension	Level	Notes
mechanics	HIGH
facts	MEDIUM	Two AWS-chain ordering / assumeRole-scope claims contradicted by upstream docs — see 🚨 Outstanding.
code correctness	HIGH

Investigation log

• Cross-sibling reads: not run (not in a templated section)
• External claim verification: 21 of 28 claims verified (1 unverifiable, 2 contradicted) · 4 specialists (numerical, cross-reference, capability, framing); 0 cross-specialist corroborations · routed: 0 inline, 16 Pass 1, 0 Pass 2, 12 Pass 3 (verified 7, contradicted 2, unverifiable 3).
• Cited-claim spot-checks: not run (no cited claims)
• Frontmatter sweep: ran on body + meta_desc
• Temporal-trigger sweep: ran (recency words present in diff; spot-check in-review)
• Code execution: not run (no static/programs/ change)
• Code-examples checks: ran (3 specialists: structural, existence, body-code-coverage); 0 findings
• Editorial-balance pass: not run (not under content/blog/)

🚨 Outstanding	⚠️ Low-confidence	💡 Pre-existing	✅ Resolved
2	6	0	0

🔍 Verification trail

28 claims extracted · 21 verified · 1 unverifiable · 2 contradicted

• L4 in content/what-is/resolve-unable-to-locate-credentials.md "The 'Unable to locate credentials' error means the AWS CLI or SDK searched every source in the credential provider chain and found nothing." → ✅ verified (evidence: The file's opening paragraph states verbatim: "The Unable to locate credentials error means the AWS CLI or SDK searched every source in the credential provider chain — environment variables, ~/.aws/credentials, EC2 or EKS instance role…; source: repo:content/what-is/resolve-unable-to-locate-credentials.md)
• L11 in content/what-is/resolve-unable-to-locate-credentials.md "The AWS credential provider chain sources include environment variables, ~/.aws/credentials, EC2 or EKS instance roles, and ECS task roles." → ✅ verified (evidence: Line 11 of the file reads: "environment variables, ~/.aws/credentials, EC2 or EKS instance roles, ECS task roles — and found nothing." This exactly matches the claim's enumeration of credential provider chain sources.; source: repo:content/what-is/resolve-unable-to-locate-credentials.md, L11)
• L11 in content/what-is/resolve-unable-to-locate-credentials.md "The 'Unable to locate credentials' error can be fixed by setting AWS_PROFILE, exporting AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, running 'aws sso login', or at…" → ✅ verified (evidence: Line 11 of the file states verbatim: "Fix it by setting AWS_PROFILE, exporting AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, running aws sso login, or attaching an instance role." — exactly matching the claim.; source: repo:content/what-is/resolve-unable-to-locate-credentials.md)
• L26 in content/what-is/resolve-unable-to-locate-credentials.md "Unlike InvalidAccessKeyId or SignatureDoesNotMatch, the 'Unable to locate credentials' error never reaches AWS — the SDK gives up locally because it can't find…" → ✅ verified (evidence: The file at L26 states: "Unlike InvalidAccessKeyId or SignatureDoesNotMatch, this error never reaches AWS. The SDK gives up locally because it can't find anything to sign a request with." This is technically accurate: `InvalidAccessKey…; source: repo:content/what-is/resolve-unable-to-locate-credentials.md)
• L28 in content/what-is/resolve-unable-to-locate-credentials.md "Some AWS SDKs surface the 'Unable to locate credentials' error as 'Unable to load credentials from any of the providers in the chain'." → ✅ verified (framing: strengthened — the claim attributes this to "some AWS SDKs" (a narrower subset); the source confirms it for AWS SDK for Java 2.x specifically, proving the clai…; evidence: The AWS SDK for Java 2.x (and other SDKs) surface this exact alternate error message. The official AWS SDK for Java docs show: "Unable to load credentials from any of the providers in the chain AwsCredentialsProviderChain(credentialsProvid…; source: https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-chain.html)
• L32 in content/what-is/resolve-unable-to-locate-credentials.md "Most AWS SDKs check sources in this order. The first source that returns credentials wins:" → ✅ verified (framing: strengthened — claim says "most AWS SDKs"; source confirms 13 named SDKs share the standardized chain, supporting "most" as a narrower subset of the broader en…; evidence: AWS documentation confirms that most SDKs use a default credential provider chain that checks sources in a defined order, stopping at the first successful source. The AWS SDK for JavaScript docs state: "All SDKs have a series of places (or…; source: https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html; https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html)
• L34-38 in content/what-is/resolve-unable-to-locate-credentials.md "The third source in the AWS credential provider chain is the shared credentials file at ~/.aws/credentials (and ~/.aws/config for profiles), selected via AWS_P…" → ❌ contradicted (framing: shifted — the claim asserts "third source" but the AWS CLI chain places the shared credentials file as the second source; the "third" position only applies to…; evidence: The AWS CLI credential chain places the shared credentials file as the second source (after environment variables), not the third. The Go SDK v1 also lists it second. Only some SDKs (Java v1/v2) place it later due to additional steps like…; source: https://docs.aws.amazon.com/cli/latest/topic/config-vars.html)
• L49 in content/what-is/resolve-unable-to-locate-credentials.md "The EC2 IMDSv2 hop limit being too low prevents containers on EC2 from reaching 169.254.169.254, and the fix is to raise HttpPutResponseHopLimit to 2." → ✅ verified (evidence: The file at L49 (table row) states: "EC2 IMDSv2 hop limit too low | Container on EC2 cannot reach 169.254.169.254 | Raise HttpPutResponseHopLimit to 2". The FAQ section further confirms: "AWS sets HttpPutResponseHopLimit to 1 by defa…; source: repo:content/what-is/resolve-unable-to-locate-credentials.md)
• L51 in content/what-is/resolve-unable-to-locate-credentials.md "Running AWS commands under sudo strips AWS_* environment variables by default." → ✅ verified (evidence: The file itself states at the "How to prevent it" section: "Don't run AWS commands under sudo. sudo strips AWS_* environment variables by default. Use sudo -E if you really need to elevate." This is consistent with the well-known L…; source: repo:content/what-is/resolve-unable-to-locate-credentials.md)
• L82 in content/what-is/resolve-unable-to-locate-credentials.md "For EKS, the recommended approach for attaching an IAM role is IRSA (IAM Roles for Service Accounts) or EKS Pod Identity." → ✅ verified (evidence: The file at line ~82 (step 3 of "How to fix it") states: "Attach an IAM instance profile (EC2), task role (ECS), or service account (EKS with IRSA or EKS Pod Identity)." This directly confirms that IRSA and EKS Pod Identity are the recomme…; source: repo:content/what-is/resolve-unable-to-locate-credentials.md)
• L95 in content/what-is/resolve-unable-to-locate-credentials.md "* Use one credential source per environment. Mixing env vars, profiles, and instance roles is the leading source of 'wait, which credentials is it using?'…" → ➖ not-a-claim (framing: not-a-claim — this is the PR author's own advisory guidance/opinion, not a third-party-attributed factual assertion; evidence: The statement is an editorial best-practice recommendation authored by the PR author, not a falsifiable factual assertion attributed to a third-party source. The characterization of mixing credential sources as "the leading source" of conf…; source: WebSearch ran query "AWS credential precedence mixing env vars profiles instance roles confusion best practice")
• L96 in content/what-is/resolve-unable-to-locate-credentials.md "'sudo' strips AWS_* environment variables by default." → ✅ verified (evidence: The file at L96 states: "Don't run AWS commands under sudo. sudo strips AWS_* environment variables by default. Use sudo -E if you really need to elevate." This is consistent with standard sudo behavior: by default, sudo resets…; source: content/what-is/resolve-unable-to-locate-credentials.md)
• L97 in content/what-is/resolve-unable-to-locate-credentials.md "GitHub Actions, GitLab, and CircleCI all support short-lived OIDC into AWS." → ✅ verified (evidence: (escalated from pass1) Official docs confirm all three: GitHub Actions uses OIDC to get "short-lived AWS credentials" (aws-actions/configure-aws-credentials); GitLab CI/CD jobs "can retrieve a temporary credential from AWS Security Token S…; source: https://github.com/aws-actions/configure-aws-credentials; https://docs.gitlab.com/ci/cloud_services/aws/; https://circleci.com/docs/guides/permissions-authentication/openid-connect-tokens/)
• L98 in content/what-is/resolve-unable-to-locate-credentials.md "* Document where credentials come from. Even a single sentence in the README about which profile or role is expected prevents this for newcomers." → ➖ not-a-claim (evidence: This is a best-practice recommendation authored by the PR author themselves — a bullet point advising readers to document credential sources in their README. It is not an attribution to a third-party source; it is the author's own original…; source: content/what-is/resolve-unable-to-locate-credentials.md L98)
• L102 in content/what-is/resolve-unable-to-locate-credentials.md "As long as you are logged into Pulumi (via 'pulumi login' or 'esc login'), 'Unable to locate credentials' cannot occur because 'esc run' always exports a compl…" → ➖ not-a-claim (evidence: The text at L102 is the PR author's own description of how Pulumi ESC works in their document: "As long as you're logged into Pulumi (pulumi login / esc login), Unable to locate credentials cannot occur — esc run always exports a c…; source: repo:content/what-is/resolve-unable-to-locate-credentials.md; intuition: The absolute guarantee ("cannot occur") is a strong claim — esc run could still fail if the OIDC role assumption fail…)
• L112 in content/what-is/resolve-unable-to-locate-credentials.md "The OIDC session duration in the example Pulumi ESC environment is set to 1 hour." → ✅ verified (evidence: The example Pulumi ESC environment YAML in the file shows duration: 1h under the OIDC configuration block: oidc: duration: 1h roleArn: arn:aws:iam::123456789012:role/PulumiESCRole sessionName: pulumi-environments-session.; source: repo:content/what-is/resolve-unable-to-locate-credentials.md)
• L113 in content/what-is/resolve-unable-to-locate-credentials.md "roleArn: arn:aws:iam::123456789012:role/PulumiESCRole" → ➖ not-a-claim (framing: strengthened — the ARN format arn:aws:iam::123456789012:role/<role-name> is the standard AWS placeholder pattern used throughout official AWS documentation;…; evidence: The value arn:aws:iam::123456789012:role/PulumiESCRole is a documentation placeholder example using the canonical AWS dummy account ID 123456789012 (confirmed by AWS official docs, e.g. "arn:aws:iam::123456789012:role/role-name") and a…; source: https://repost.aws/knowledge-center/iam-resource-policy-format)
• L127 in content/what-is/resolve-unable-to-locate-credentials.md "The AWS provider's 'assumeRole' configuration supplies credentials inside a Pulumi deployment, so a 'pulumi up' never depends on the operator's shell." → ❌ contradicted (framing: narrowed — claim broadens the source: source shows assumeRole assumes a role on top of existing base credentials; claim asserts it fully replaces shell credent…; evidence: (escalated from pass1) The Pulumi AWS provider's assumeRole configuration assumes a role in the security context of an IAM user running the program, but still requires base credentials to be present. The how-to guides explicitly state "I…; source: https://www.pulumi.com/registry/packages/aws/how-to-guides/aws-ts-assume-role/ and https://www.pulumi.com/registry/packages/aws/api-docs/provider/)
• L131 in content/what-is/resolve-unable-to-locate-credentials.md "The page /what-is/resolve-list-buckets-invalid-access-key-id/ exists as a cross-reference target." → ✅ verified (evidence: The file content/what-is/resolve-list-buckets-invalid-access-key-id.md exists in the repository with a matching title and content about resolving the InvalidAccessKeyId error when calling ListBuckets, confirming the cross-reference targe…; source: repo:content/what-is/resolve-list-buckets-invalid-access-key-id.md)
• L131-134 in content/what-is/resolve-unable-to-locate-credentials.md "The cross-reference target /what-is/resolve-list-buckets-signature-does-not-match/ exists as a page on the Pulumi site." → ✅ verified (evidence: The file content/what-is/resolve-list-buckets-signature-does-not-match.md exists in the repository with a valid front matter and full content, confirming the page at /what-is/resolve-list-buckets-signature-does-not-match/ exists on the…; source: repo:content/what-is/resolve-list-buckets-signature-does-not-match.md)
• L133-134 in content/what-is/resolve-unable-to-locate-credentials.md "* InvalidClientTokenId — temporary credentials present but inconsistent." → ✅ verified (framing: strengthened — the source says "security token included in the request is invalid"; the claim summarizes this as "temporary credentials present but inconsisten…; evidence: The file content/what-is/resolve-list-buckets-invalid-client-token-id.md exists and describes the error as occurring when "the security token included in the request is invalid," which is consistent with the summary "temporary credential…; source: repo:content/what-is/resolve-list-buckets-invalid-client-token-id.md)
• L148 in content/what-is/resolve-unable-to-locate-credentials.md "AWS sets HttpPutResponseHopLimit to 1 by default, which doesn't reach inside Docker containers on EC2." → ✅ verified (framing: strengthened — claim narrows the general default-of-1 behavior to the specific Docker-on-EC2 scenario; source's broader form proves the claim as a subset.; evidence: AWS EC2 docs confirm the default HttpPutResponseHopLimit is 1, and multiple authoritative sources confirm this prevents Docker containers from reaching the IMDS. Per the AWS docs: "When -1 (no preference) is specified, at launch, the value…; source: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-IMDS-new-instances.html; https://oneuptime.com/blog/post/2026-02-12-use-imdsv2-for-secure-instance-metadata-access/view)
• L148 in content/what-is/resolve-unable-to-locate-credentials.md "Increasing HttpPutResponseHopLimit to 2 fixes the 'Unable to locate credentials' error for containers on EC2." → ✅ verified (evidence: The file itself states in the causes table: "EC2 IMDSv2 hop limit too low | Container on EC2 cannot reach 169.254.169.254 | Raise HttpPutResponseHopLimit to 2" and in the FAQ: "AWS sets HttpPutResponseHopLimit to 1 by default, which…; source: repo:content/what-is/resolve-unable-to-locate-credentials.md)
• L152 in content/what-is/resolve-unable-to-locate-credentials.md "NoCredentialProviders is the Go SDK's version of the 'Unable to locate credentials' error." → ✅ verified (evidence: The AWS SDK for Go (aws-sdk-go) defines ErrNoValidProvidersFoundInChain = awserr.New("NoCredentialProviders", ...) in aws/credentials/chain_provider.go, confirming NoCredentialProviders is the Go SDK's error code for when no valid cr…; source: https://pkg.go.dev/github.com/aws/aws-sdk-go/aws/credentials and https://github.com/aws/aws-sdk-go/blob/main/aws/credentials/chain_provider.go)
• L156 in content/what-is/resolve-unable-to-locate-credentials.md "Region-related failures in AWS show up as 'You must specify a region' or as a 301 redirect when calling S3." → ✅ verified (evidence: (escalated from pass1) The "You must specify a region" error is a well-documented AWS CLI/SDK error when no region is configured. AWS S3 returning a 301 redirect when the wrong regional endpoint is used is also a well-known AWS behavior, a…; source: WebSearch ran query "AWS SDK 'You must specify a region' S3 301 redirect region error"; corroborated by https://tecadmin.net/resolving-the-you-must-specify-a-region-error-in-aws/ and https://how.wtf/you-must-specify-a-region-error-aws.html)
• L164-166 in content/what-is/resolve-unable-to-locate-credentials.md "The page /docs/esc/environments/configuring-oidc/aws/ exists as a cross-reference target for configuring OIDC between Pulumi ESC and AWS." → 🤷 unverifiable (evidence: verification did not converge within 8 turns)
• L166 in content/what-is/resolve-unable-to-locate-credentials.md "* AWS provider reference" → ✅ verified (evidence: The pulumi/registry repo confirms the /registry/packages/aws/api-docs/provider path exists: the AWS installation-configuration page links to ../api-docs/provider (resolving to the same URL), and the registry's directory-structure test…; source: gh search code --owner pulumi "api-docs/provider" --repo pulumi/registry (result: pulumi/registry:themes/default/content/registry/packages/aws/installation-configuration.md references ../api-docs/provider))
• L167 in content/what-is/resolve-unable-to-locate-credentials.md "* AWS CLI configuration and credential files" → ✅ verified (evidence: The AWS docs page at https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html exists and is titled "Configuration and credential file settings in the AWS CLI," matching the link text "AWS CLI configuration and credential…; source: https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html)

🚨 Outstanding in this PR

These must be resolved or refuted before merging.

• [L34-38] content/what-is/resolve-unable-to-locate-credentials.md — "The third source in the AWS credential provider chain is the shared credentials file at ~/.aws/credentials..." — verdict: contradicted (framing: shifted). The chain ordering in the doc (env vars → SSO cache → shared credentials → ECS → IMDS) puts SSO at Update in the wake of renamepocalypse #2 and the shared credentials file at Improve our TypeScript documentation story #3, but the AWS CLI and most SDK chains place the shared credentials file before SSO. The opening sentence ("Most AWS SDKs check sources in this order") makes this a general claim rather than the author's own ordering, so the mismatch with the standard chain matters. Source: https://docs.aws.amazon.com/cli/latest/topic/config-vars.html.

  Suggestion — either swap rows 2 and 3 to match the canonical AWS CLI chain, or weaken the framing so it doesn't promise a single canonical order. For example:

  Most AWS SDKs check sources in roughly this order, with some variation between SDKs and CLI versions. The first source that returns credentials wins:
  
  1. **Environment variables** — `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, optionally `AWS_SESSION_TOKEN`.
  1. **Shared credentials file** — `~/.aws/credentials` (and `~/.aws/config` for profiles), selected via `AWS_PROFILE` or `--profile`.
  1. **AWS SSO / IAM Identity Center cache** — populated by `aws sso login`; referenced from a profile in `~/.aws/config`.
  1. **Container credentials** — ECS task role, served on `169.254.170.2`.
  1. **Instance metadata** — EC2 instance profile or EKS pod identity, served on `169.254.169.254`.
  

• [L127] content/what-is/resolve-unable-to-locate-credentials.md — "the AWS provider's assumeRole configuration supplies credentials inside a deployment, so a pulumi up never depends on the operator's shell." — verdict: contradicted (framing: narrowed). assumeRole calls sts:AssumeRole, which itself needs caller credentials — those still come from the shell (or from another configured source). The provider only swaps the role; it doesn't synthesize the underlying identity. Source: https://www.pulumi.com/registry/packages/aws/how-to-guides/aws-ts-assume-role/.

  Suggestion — replace the absolute phrasing with a more accurate description of what assumeRole does:

  For Pulumi programs themselves, the AWS provider's [`assumeRole` configuration](/registry/packages/aws/api-docs/provider/) layers a role assumption on top of base credentials supplied by ESC, the environment, or an instance role — so once those base credentials are in place, a `pulumi up` resolves to the assumed role's permissions without further shell configuration.
  

⚠️ Low-confidence

Review each and resolve as appropriate — these don't block the PR.

• [L165] content/what-is/resolve-unable-to-locate-credentials.md — "Configuring OIDC between Pulumi ESC and AWS" link uses the legacy /docs/esc/environments/configuring-oidc/aws/ path. The link works today (the canonical page at content/docs/esc/guides/configuring-oidc/aws.md declares it as an alias), but other docs in this repo link to the canonical /docs/esc/guides/configuring-oidc/aws/. Consider updating to the canonical path so the link doesn't quietly bit-rot if the alias is ever removed.

Style findings

Found by pattern-based linting; Findings may be false positives.

• line 65: [style] weasel word — 'usually' is a weasel word!
• line 142: [style] first person — Avoid first-person pronouns such as 'my'.
• line 146: [style] first person — Avoid first-person pronouns such as 'My'.
• line 146: [style] punctuation — Commas and periods go inside quotation marks.
• line 154: [style] first person — Avoid first-person pronouns such as ' I '.

📋 Triaged verifier findings

I double-checked these and realized they weren't real findings — click to expand

• [L164-166] content/what-is/resolve-unable-to-locate-credentials.md — "The page /docs/esc/environments/configuring-oidc/aws/ exists as a cross-reference target..." — verdict was unverifiable (verifier ran out of turns). Mis-sourced: The canonical page lives at content/docs/esc/guides/configuring-oidc/aws.md and declares /docs/esc/environments/configuring-oidc/aws/ as an alias, so the link resolves. See separate ⚠️ note about preferring the canonical path.

💡 Pre-existing issues in touched files (optional)

No pre-existing issues in touched files.

✅ Resolved since last review

No items resolved since the last review.

📜 Review history

• 2026-05-20T16:52:18Z — Flagged two contradicted factual claims (credential-chain ordering at L34-38; over-broad assumeRole claim at L127); noted alias-vs-canonical-path nit on the ESC OIDC link. (f633dc9)

---

Need a re-review? Want to dispute a finding? Mention @claude and include #update-review.
(For ad-hoc questions or fixes, just @claude — no hashtag.)