FREE TOOL

AWS Credentials Chain Troubleshooter

Paste your ~/.aws/config, choose the AWS CLI, an SDK or Terraform, and see the credential provider chain it follows, where your profile gets its credentials and what breaks it.

TOOL

PROFILE

Chains of all tools →Where the tools differ →Decode an access key ID →

See the chain ↓

PROFILE ADMIN GETS ITS CREDENTIALS

[profile admin] assumes arn:aws:iam::444455556666:role/Admin with the credentials of [profile dev], asking for an MFA code:

[profile dev] gets the role Developer in account 111122223333 from IAM Identity Center, signed in through [sso-session my-sso] (aws sso login).

SEARCHED IN THIS ORDER, FIRST MATCH WINS

Command line optionsWINS IF SET--profile picks the profile and overrides AWS_PROFILE; no option takes the keys themselves.
Environment variablesWINS IF SETAWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN. When set, they win over any profile.
Assume roleUSEDrole_arn with source_profile or credential_source.
Assume role with web identityNOT REACHEDrole_arn with web_identity_token_file, or AWS_ROLE_ARN with AWS_WEB_IDENTITY_TOKEN_FILE.
IAM Identity CenterNOT REACHEDsso_session (or the legacy sso_start_url) with sso_account_id and sso_role_name, signed in with aws sso login.
Shared credentials fileNOT REACHEDAccess keys in the profile's section of ~/.aws/credentials - not part of what you pasted.
Console login credentialsNOT REACHEDlogin_session, signed in with aws login.Not in this tool's own list; placed where the Boto3 guide puts it - both are built on botocore.
Credential processNOT REACHEDcredential_process: a command that prints the credentials.
Keys in the config fileNOT REACHEDaws_access_key_id and aws_secret_access_key in the profile in ~/.aws/config.
Container credentialsNOT REACHEDThe role of an Amazon ECS task or an Amazon EKS pod, from the container credentials endpoint.
EC2 instance roleNOT REACHEDThe role of the EC2 instance profile, from the instance metadata service.

Order from AWS CLI: Configuration and credentials precedence. Check what is really used: aws configure list --profile admin

No problem found in the profile for AWS CLI v2.

THE SAME PROFILE IN EVERY TOOL

AWS CLI v2	Assume role	OK
Python (Boto3)	Assume role	OK
JavaScript v3 (Node.js)	fromIni()	1 problem
Java 2.x	The shared credentials and config files	2 problems
Go v2	Shared configuration files	OK
Terraform	Shared configuration file	OK

SDK credentials, profiles and IAM roles are core AWS Developer Associate topicsTry free DVA-C02 practice questions with answers and explanations.DVA-C02 questions →

How the AWS CLI and SDKs look for credentials

Every AWS tool searches a list of places for credentials, in a fixed order, and stops at the first one that has them - the credential provider chain. Credentials set in code (in an SDK) or in Terraform's provider block always come first, and environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN) come before any profile in every tool below. After that the tools differ:

Tool	Order after code and environment variables
AWS CLI v2	assume role, assume role with web identity, IAM Identity Center, `~/.aws/credentials`, credential process, keys in `~/.aws/config`, container credentials, EC2 instance role
Python (Boto3)	assume role, assume role with web identity, IAM Identity Center, `~/.aws/credentials`, console login, keys in `~/.aws/config`, the Boto2 config file, container credentials, EC2 instance role
JavaScript v3 (Node.js)	`fromSSO()`, `fromIni()` (the profile in both files), `fromLoginCredentials()`, `fromProcess()`, `fromTokenFile()`, container credentials, EC2 instance role
Java 2.x	Java system properties before the environment, then the web identity token from the environment, the profile (web identity, IAM Identity Center, assume role, console login, credential process, keys), container credentials, EC2 instance role
Go v2	the web identity token from the environment, `~/.aws/credentials`, `~/.aws/config`, the ECS task role, EC2 instance role
Terraform (AWS provider)	`~/.aws/credentials`, `~/.aws/config`, container credentials (ECS, CodeBuild, or the pod's role on EKS), EC2 instance role

Each list is from the tool's own guide (see the references); Terraform's is HashiCorp's guide for its AWS provider, which says its order matches the AWS CLI and the SDK for Go v2. The AWS CLI's guide does not place console login and Boto3's does not place the credential process; both tools are built on botocore, so the troubleshooter places each where the other one's guide puts it.

Where the tools differ for the same profile

IAM Identity Center before the profile file in JavaScript. The SDK for JavaScript tries fromSSO() before fromIni(), so a profile with both SSO settings and keys uses SSO.
Extra dependencies in Java. The SDK for Java 2.x reads IAM Identity Center profiles only with the sso and ssooidc modules, and console login only with signin, in the project's dependencies.
MFA. The AWS CLI and Boto3 prompt for the code of mfa_serial (and Boto3 waits for it, even in a script); the SDK for Java 2.x does not support mfa_serial (nor duration_seconds), and the SDK for JavaScript needs an mfaCodeProvider in code.
Console login (login_session, written by aws login) needs the AWS CLI 2.32.0 or later, and Boto3 1.41.0 or later with the AWS Common Runtime.
Environment variables in Go. The SDK for Go uses keys from the environment whenever they are set, no matter which profile you choose.
Roles in Terraform's provider block. Terraform can assume a role from an assume_role block in provider "aws" instead of the profile, and chain several roles there. Its guide does not mention IAM Identity Center or console login profiles; the troubleshooter reads them from the config file as the SDK for Go v2 does, whose order the guide says it follows.

Config file mistakes that break the chain

Mistake	What happens
`[dev]` in `~/.aws/config`	Not a profile: in the config file every profile but `[default]` is `[profile dev]`. The credentials file is the other way round.
`role_arn` alone	A role profile also needs `source_profile`, `credential_source` or `web_identity_token_file` - and never both of the first two.
`source_profile` naming a missing profile, or a loop	Roles are assumed one after another until a profile has credentials of its own; the chain has to end in one.
`sso_start_url` in the profile	The legacy SSO configuration: a fixed eight-hour session that never refreshes. Use an `[sso-session]` section.
Settings only in `[default]`	`[default]` is not inherited: a named profile gets none of its values.

Credential errors

The troubleshooter recognizes the errors the CLI and SDKs print when the chain ends in the wrong place, from "Unable to locate credentials" to "The security token included in the request is expired". The same catalog, together with decoding an access key ID to its account, is in the AWS Access Key ID Decoder. Before anything else, ask the tool itself:

aws configure list          # which key, profile and Region are used, and where each comes from
aws sts get-caller-identity # which account and user or role the credentials belong to
env | grep AWS_             # environment variables win over every profile

Frequently asked questions

Is it safe to paste my ~/.aws/config here?

Yes. It is read in your browser: nothing you paste is uploaded, processed on a server or stored. The config file normally holds no secrets, and lines that do - aws_secret_access_key, aws_session_token or a value that looks like a secret key - are rejected without being read. The page only counts which tool was chosen and what kind of problem it found, never the text or profile names.

Why are my ~/.aws/credentials not pasted too?

That file holds the secrets. The troubleshooter marks where it would win instead: when a step says "wins if present", keys in the profile's section of ~/.aws/credentials are used before anything below it.

Which profile does a tool use?

The one named by --profile (the AWS CLI) or in code, then AWS_PROFILE, then [default]. The AWS CLI's --profile overrides AWS_PROFILE.

Why does my SSO profile work in the CLI but not in my application?

Choose the SDK above: Java needs the sso and ssooidc modules, and a role profile with mfa_serial does not work in Java at all, or in JavaScript without an MFA code provider. Also check that the application runs as the same user and sees the same AWS_PROFILE.

References

AWS SDKs and Tools: standardized credential providers
AWS CLI: configuration and credentials precedence
Boto3: credentials
SDK for JavaScript v3: set credentials in Node.js
SDK for JavaScript v3: credential providers (fromIni, mfaCodeProvider)
SDK for Java 2.x: default credentials provider chain
SDK for Java 2.x: credentials for interactive development
SDK for Go v2: configure the SDK
Terraform AWS provider: authentication and configuration
Shared config and credentials files
Assume role credential provider
IAM Identity Center credential provider