If you’ve ever worked with AWS SDKs or the boto3 library in Python, you’ve probably seen this error at least once:
botocore.exceptions.NoCredentialsError: Unable to locate credentials
It’s a common issue that can be frustrating, especially when your code works locally but fails in production or inside a container. In this post, we’ll unpack why this happens, how AWS credentials work behind the scenes, and the most reliable ways to fix it.
What This Error Actually Means
When you see the message “Unable to locate credentials,” it simply means that botocore (the core library behind boto3) tried to find your AWS credentials—but couldn’t.
In other words, the SDK doesn’t know who you are.
Without credentials, AWS has no way of verifying your identity or giving you access to resources like S3, DynamoDB, or Lambda.
How AWS Credentials Work
Before fixing the issue, it helps to understand how credentials are normally found.
When you use boto3 or any AWS SDK, it looks for credentials in a specific order known as the AWS credentials chain. The search order is:
- Environment variables
- AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
- (Optional) AWS_SESSION_TOKEN for temporary credentials
- AWS credentials file
- Typically located at ~/.aws/credentials
- AWS config file
- Located at ~/.aws/config (may include a profile)
- Assumed roles or profiles
- For example, if you run aws sso login or assume an IAM role
- EC2 or ECS instance metadata
- Used automatically when running inside AWS infrastructure (like EC2, ECS, or Lambda)
If none of these are found, the SDK throws the NoCredentialsError.
Common Causes
Let’s look at why this happens in real projects:
1. You haven’t configured AWS credentials
If you’ve just installed boto3 and haven’t yet run aws configure, the SDK simply has nothing to work with.
2. You’re using the wrong profile
Sometimes developers specify a profile name that doesn’t exist in their credentials file.
3. Environment variables aren’t set
In CI/CD pipelines or Docker containers, environment variables might not be passed properly.
4. The code is running in a different user context
If a script runs under a system user or cron job, it might not have access to your ~/.aws directory.
5. Metadata access is blocked
When running inside AWS (for example, EC2), credentials are usually fetched from the instance metadata service. If that’s disabled or blocked, the SDK can’t retrieve them.
How to Fix the Error
Now, let’s go through the most reliable solutions.
1. Configure AWS credentials locally
The simplest fix is to use the AWS CLI to set up credentials:
aws configure
You’ll be prompted for:
- AWS Access Key ID
- AWS Secret Access Key
- Default region
- Output format
This creates or updates the ~/.aws/credentials and ~/.aws/config files.
You can then test your credentials by running:
aws sts get-caller-identity
If this returns your AWS account info, your credentials are valid.
2. Set credentials using environment variables
If you can’t or don’t want to use the CLI, export credentials directly:
Linux/Mac:
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
Windows (PowerShell):
setx AWS_ACCESS_KEY_ID “your-access-key”
setx AWS_SECRET_ACCESS_KEY “your-secret-key”
Then restart your shell and rerun your script.
3. Use an AWS credentials file with profiles
If you manage multiple AWS accounts, create profiles in ~/.aws/credentials like this:
[default]
aws_access_key_id = YOUR_DEFAULT_KEY
aws_secret_access_key = YOUR_DEFAULT_SECRET
[dev]
aws_access_key_id = YOUR_DEV_KEY
aws_secret_access_key = YOUR_DEV_SECRET
In your Python code, specify which profile to use:
import boto3
session = boto3.Session(profile_name=’dev’)
s3 = session.client(‘s3’)
This avoids hardcoding credentials and keeps things organized.
4. Use IAM roles inside AWS
When running code on EC2, ECS, or Lambda, you should never hardcode credentials.
Instead, attach an IAM role to your instance or function. AWS automatically injects temporary credentials through the instance metadata service.
For example, in EC2:
- Create an IAM role with necessary permissions (e.g., AmazonS3ReadOnlyAccess)
- Attach it to your EC2 instance
- Then just run:
import boto3
s3 = boto3.client(‘s3’)
s3.list_buckets()
No credentials file or environment variables required — AWS handles it securely for you.
5. Verify permissions and configuration paths
Sometimes credentials exist but can’t be read due to permission issues.
Check that:
- The file permissions for ~/.aws/credentials allow read access.
- The path exists and is spelled correctly.
- You’re not running your script under a restricted system user.
For example:
ls -la ~/.aws/
You should see both credentials and config files, owned by your user.
6. Debug the credential chain
If you’ve tried all the above and still see the error, enable debugging to trace what’s happening.
Run your Python script with logging:
import boto3
import logging
logging.basicConfig(level=logging.DEBUG)
s3 = boto3.client(‘s3’)
s3.list_buckets()
You’ll see output showing exactly where boto3 looked for credentials and what it found.
Best Practices for Managing AWS Credentials
To prevent the error from coming back — and to follow AWS security best practices — consider these guidelines:
- Never hardcode credentials in your code.
Use environment variables or IAM roles instead. - Use separate IAM users or roles for each environment.
Avoid sharing root or admin keys across multiple projects. - Rotate keys regularly.
Old keys should be deactivated and replaced periodically. - Use AWS Single Sign-On (SSO) or federated access
For teams or organizations, this is more secure and manageable than static keys. - Restrict permissions using least privilege.
Only give the minimal access necessary for your application to function.
Example: Working Configuration in a Local Environment
Here’s a complete working example using a profile:
Step 1: Add credentials
~/.aws/credentials:
[projectx]
aws_access_key_id = ABCDEFGHIJKL12345
aws_secret_access_key = abcdefghijklmnopqrstuvwxyz1234567890
Step 2: Python script
import boto3
session = boto3.Session(profile_name=’projectx’)
s3 = session.client(‘s3’)
response = s3.list_buckets()
for bucket in response[‘Buckets’]:
print(bucket[‘Name’])
This will list your S3 buckets successfully — no NoCredentialsError this time.
Final Thoughts
The error “botocore.exceptions.NoCredentialsError: Unable to locate credentials” isn’t as mysterious as it looks. It’s just a sign that boto3 can’t find valid authentication details.
Once you understand how AWS credentials are discovered and configured, fixing it becomes straightforward. Whether you’re developing locally, deploying in AWS, or running a containerized app, following the credential chain and applying IAM best practices will keep your environment both functional and secure.
Reliable credential management isn’t just about avoiding errors — it’s about protecting your AWS resources from accidental exposure and maintaining a secure, maintainable workflow.