Unable to locate credentials
This error occurs when the AWS CLI or SDK cannot find any valid authentication credentials in the default credentials provider chain.
Usually happens because:
- ☑ No configuration profile has been created on the client machine
- ☑ Active workload lacks EC2 IAM Instance Profile or ECS Task execution role bindings
- ☑ Stale environment variable configurations mask active config files
🔍 Quick Checklist:
What is Unable to locate credentials?
An 'Unable to locate credentials' error is raised by AWS CLI or SDK clients during initialization if the credentials provider chain fails to locate any credentials. AWS clients search for credentials in a specific sequence: environment variables, the default credentials file ('~/.aws/credentials'), container credentials (ECS task roles), and lastly, EC2 instance metadata (IMDS). If all locations are empty, the client halts execution.
Common Causes
- No credentials configured: The local client machine has never run 'aws configure' and contains no credentials file.
- Wrong config file path or permissions: The credentials file is saved in a non-standard location, has incorrect file permissions, or the home environment variable is unset.
- Container or VM instance role missing: Workloads scheduled on AWS EC2 or ECS assume they can fetch credentials via metadata endpoints, but no IAM Instance Profile or Task Role is attached.
| Cause | Frequency |
|---|---|
| Missing configuration file (never ran 'aws configure') | ⭐⭐⭐⭐⭐ |
| Workload running on EC2/ECS without attached IAM Instance Profile | ⭐⭐⭐⭐ |
| Incorrect profile name requested (using --profile with wrong naming) | ⭐⭐⭐ |
Common Mistakes
- Specifying a profile name via `--profile` flag but omitting the corresponding configuration section inside `~/.aws/config` or `~/.aws/credentials`.
- Relying on local credential files inside Docker containers without mounting host `~/.aws` directories or passing environment variables.
How to Fix
AWS Operations & Verification
Initialize the default credentials configuration using interactive CLI command flags.
# Run configure and input your access parameters
$ aws configure
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-east-1
Default output format [None]: jsonPlatform Specific Fixes
Inspect credentials directory structure and check file access rights.
# 1. Verify existence of configuration folder
ls -la ~/.aws/
# 2. Check variables export
echo $AWS_ACCESS_KEY_IDBest Practices
- Adopt IAM instance profiles or IAM roles for service accounts (IRSA) inside containerized infrastructure to avoid hardcoding access keys.
- Adopt script checks to verify active auth contexts prior to running tasks.
Frequently Asked Questions (FAQ)
Q: What does 'Unable to locate credentials' mean?
This means the AWS CLI or SDK looked through its entire list of default credential locations (environment variables, config files, IAM instance metadata) and found absolutely nothing to authenticate with.
Q: How do I solve this on my local development machine?
Run: 'aws configure'. It will prompt you for your AWS Access Key ID, Secret Access Key, Default Region, and Output format, and then save them to '~/.aws/credentials' and '~/.aws/config'.
Q: Why does my code run locally but fail on AWS EC2 or ECS with this error?
Locally, your SDK uses your local credentials file. On AWS, it expects to fetch credentials from the Instance Metadata Service (IMDS) or ECS Task Metadata. You must attach an IAM Instance Profile (for EC2) or an ECS Task Execution Role to the resource, or the SDK will fail to locate credentials.
Q: How do I specify a non-default profile name?
If your credentials are saved under a named profile (e.g. '[staging]'), you must pass the profile name to the CLI using '--profile staging' or set the environment variable 'export AWS_PROFILE=staging'. Otherwise, the CLI only looks for the '[default]' profile.