AWS: NoCredentialsError — Unable to locate credentials
NoCredentialsError — no AWS credentials found
Verified against AWS SDK docs: Credential provider chain, AWS IAM docs: Best practices for managing AWS access keys, boto3 docs: Credentials configuration · Updated June 2026
> quick_fix
The AWS SDK searched all credential sources and found nothing. Fix: run aws configure to set up ~/.aws/credentials, set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables, or attach an IAM role if running on EC2/Lambda/ECS.
# Option 1 — configure credentials file:
aws configure
# Enter: Access Key ID, Secret Access Key, region, output format
# Option 2 — environment variables:
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
export AWS_DEFAULT_REGION=us-east-1
# Option 3 — verify current identity:
aws sts get-caller-identityWhat causes this error
The AWS SDK follows a credential provider chain: (1) environment variables, (2) shared credentials file (~/.aws/credentials), (3) AWS config file (~/.aws/config), (4) ECS container credentials, (5) EC2 instance profile / IMDSv2. NoCredentialsError means the SDK walked this entire chain and found nothing. The most common cause on a developer machine is never running aws configure. In production, the most common cause is a Lambda/EC2/ECS service missing its IAM role attachment.
How to fix it
- 01
step 1
Check if credentials exist
First, check if any credentials are configured. If the file exists and has a [default] profile with access keys, credentials are set.
# Check credentials file: cat ~/.aws/credentials # Check environment variables: echo $AWS_ACCESS_KEY_ID # Check if any identity is configured: aws sts get-caller-identity - 02
step 2
For local development: run aws configure
The simplest fix for local development. This creates ~/.aws/credentials with your access key pair.
aws configure # AWS Access Key ID: AKIA... # AWS Secret Access Key: (paste secret) # Default region name: us-east-1 # Default output format: json - 03
step 3
For production: attach an IAM role
On EC2, Lambda, ECS, or EKS, never use access keys. Attach an IAM role instead — the SDK picks up temporary credentials from the instance metadata service automatically.
# Lambda: set the execution role in the function config aws lambda update-function-configuration \ --function-name my-function \ --role arn:aws:iam::123456789:role/my-lambda-role # EC2: attach an instance profile aws ec2 associate-iam-instance-profile \ --instance-id i-1234567890 \ --iam-instance-profile Name=my-profile - 04
step 4
For named profiles: set AWS_PROFILE
If you have multiple profiles in ~/.aws/credentials (e.g., [dev] and [prod]), set the AWS_PROFILE environment variable to tell the SDK which to use.
export AWS_PROFILE=dev aws sts get-caller-identity
How to verify the fix
- aws sts get-caller-identity returns your account and ARN without errors.
- Your application's AWS SDK calls succeed.
- The credential source matches what you expect (IAM user vs. role vs. SSO).
Why NoCredentialsError happens at the runtime level
The AWS SDK implements a credential provider chain — a sequence of credential sources checked in order. In Python's boto3, this is botocore.credentials.create_credential_resolver() which builds a list of providers: EnvProvider, SharedCredentialProvider, ConfigProvider, BotoProvider, AssumeRoleProvider, ContainerMetadataProvider, InstanceMetadataProvider. Each provider's load() method returns credentials or None. If every provider returns None, the resolver raises NoCredentialsError. The error surfaces at the point of the first AWS API call, not at client creation — the SDK defers credential resolution until a request is actually made.
Common debug mistakes for NoCredentialsError
- Setting AWS_ACCESS_KEY_ID but forgetting AWS_SECRET_ACCESS_KEY — the SDK finds a partial credential set and throws a different error ('Partial credentials found'). Both must be set together.
- Running aws configure in one terminal but running the application in another — environment variables don't cross terminal sessions. If you set credentials via env vars, make sure the application's process inherits them.
- Using access keys in Docker containers instead of passing IAM role credentials — if the container runs on ECS, the SDK automatically picks up task role credentials. Baking access keys into Docker images is a security risk.
- Assuming credentials work because aws s3 ls works in the shell — the CLI and your application may use different profiles or credential sources. The CLI might use AWS_PROFILE=admin while your app uses the [default] profile.
- Not understanding that SDK credential errors are lazy — the error fires on the first API call, not when you create the client. Creating boto3.client('s3') succeeds even with no credentials; s3.list_buckets() is where it fails.
When NoCredentialsError signals a deeper problem
Recurring NoCredentialsError across a team usually means there's no standardized credential management. Each developer configures credentials differently — some use env vars, some use ~/.aws/credentials, some use SSO, some have stale keys. The fix is standardizing on AWS SSO (aws configure sso) for developer machines and IAM roles for all production services. SSO credentials auto-expire and auto-refresh, eliminating the 'my keys rotated and now nothing works' failure mode. Pair this with a pre-commit hook that scans for hardcoded AWS keys (using tools like git-secrets or trufflehog) to prevent credential leaks.
Editor's take
The NoCredentialsError that cost me the most time was in a Docker Compose setup. The application worked perfectly on my laptop (using ~/.aws/credentials) but threw NoCredentialsError inside the Docker container. The credentials file wasn't mounted into the container, and I hadn't set env vars in docker-compose.yml. The fix was a two-line volume mount: ~/.aws:/root/.aws:ro. But I spent 40 minutes checking IAM policies, regenerating keys, and testing with the CLI before realizing the container simply couldn't see my local credentials.
The insight that separates a junior from a senior AWS developer is understanding that NoCredentialsError and AccessDenied are completely different problems. NoCredentialsError means 'I don't know who you are' — no identity at all. AccessDenied means 'I know who you are but you're not allowed to do this' — identity exists but permissions are wrong. The first is a configuration problem; the second is a policy problem. Debugging one as if it's the other wastes hours.
Adjacent errors: 'ExpiredTokenError: The security token included in the request is expired' (credentials existed but expired — common with SSO and assumed roles), 'InvalidClientTokenId: The security token included in the request is invalid' (the access key ID doesn't exist in IAM — either deleted or typo), and AccessDenied (credentials work but lack the specific IAM permission needed).
By Bikram Nath · Curator · Updated June 2026
Frequently asked questions
What's the credential provider chain order?
Environment variables → shared credentials file (~/.aws/credentials) → AWS config file (~/.aws/config with credential_process) → SSO → ECS container credentials → EC2 instance metadata. The SDK stops at the first source that provides credentials.
Should I use access keys in production?
No. Access keys are long-lived and can be leaked. In production, use IAM roles (EC2 instance profiles, Lambda execution roles, ECS task roles). Roles provide temporary credentials that rotate automatically.
Why does my Lambda get NoCredentialsError?
The Lambda function is missing an execution role, or the role doesn't have the permissions needed. Check the function's configuration for the role ARN, and verify the role's policy grants access to the AWS services your function calls.