> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastfoundation.nimble.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Step-by-step help for common AWS IAM Identity Center (SSO) authentication and configuration issues

<Note>
  If you're having trouble signing in or using **AWS IAM Identity Center (formerly AWS SSO)**, you're not alone. Most problems are caused by expired tokens or small configuration mistakes, and they can usually be fixed quickly.
</Note>

# Common Problems and Fixes

## 1. I Can't Log In (Authentication Issues)

Start here if you cannot log in, your session has expired, or you see errors involving tokens.

### 1.1 My SSO Token Has Expired

If you see errors about your session expiring or your token being invalid, don't worry—this happens frequently when your login session times out.

**You might see messages like:**

* `Token has expired and refresh failed`
* `The SSO session associated with this profile has expired or is otherwise invalid`

**How to Fix It:**

<Steps>
  <Step title="Re-authenticate with AWS IAM Identity Center (SSO)">
    Run the following command to refresh your login session.\
    This will open your browser and ask you to sign in again:

    ```bash theme={null}
    aws sso login --profile <project>-<account_name>
    ```
  </Step>

  <Step title="Clear cached SSO credentials if needed">
    If re-authentication doesn't work, clear your cached credentials and try again:

    ```bash theme={null}
    # Remove cached SSO credentials
    rm -rf ~/.aws/sso/cache/

    # Re-authenticate
    aws sso login --profile <project>-<account_name>
    ```
  </Step>

  <Step title="Verify your authentication worked">
    Run this command to confirm that your identity is valid:

    ```bash theme={null}
    aws sts get-caller-identity --profile <project>-<account_name>
    ```
  </Step>
</Steps>

### 1.2 Browser Authentication Problems

Sometimes the browser doesn't open automatically, or the login page fails to load.

**You might see messages like:**

* Browser doesn't open automatically
* "Device authorization failed"

**How to Fix It:** Open the browser manually

1. Look for the authentication URL in the CLI (Command Line Interface) output
2. Copy and paste it into your browser
3. Complete the sign-in process
4. Return to the CLI to continue

***

## 2. My Profile Isn't Working (Configuration Issues)

Check here if the AWS CLI cannot find your profile or complains about your region.

### 2.1 Profile Could Not Be Found

**You might see messages like:**

* `The config profile 'myprofile' could not be found`
* `Profile not found`

**How to Fix It:**

<AccordionGroup>
  <Accordion title="Check profile syntax" icon="code">
    Open your `~/.aws/config` file and verify that the syntax is correct.

    ```ini theme={null}
    # ✅ Correct syntax
    [profile <project>-<account_name>]
    sso_session = <project>
    sso_account_id = <account_name>
    sso_role_name = <role-name>
    region = us-west-2

    # ❌ Common mistakes
    [<project>-<account_name>]  # Missing "profile"
    [ profile <project>-<account_name> ]  # Extra spaces
    ```
  </Accordion>

  <Accordion title="List available profiles" icon="list">
    Run these commands to check which profiles exist:

    ```bash theme={null}
    aws configure list-profiles
    aws configure list --profile <project>-<account_name>
    ```
  </Accordion>
</AccordionGroup>

### 2.2 Region Configuration Problems

**You might see messages like:**

* `Invalid region specified`
* Services not accessible in expected region

**How to Fix It:**

```bash theme={null}
# Check current region configuration
aws configure get region --profile <project>-<account_name>

# Set region for profile
aws configure set region us-west-2 --profile <project>-<account_name>

# Override region for one command only
aws s3 ls --region us-east-1 --profile <project>-<account_name>
```

## 3. I Don't Have Access (Permission Issues)

### 3.1. Access Denied Errors

You might see messages like:

* Error: `AccessDenied: User is not authorized to perform this action`
* Error: `Forbidden: Insufficient permissions`

**How to Fix It:**

<Steps>
  <Step title="Verify Current Identity">
    ```bash theme={null}
    aws sts get-caller-identity --profile <project>-<account_name>
    ```

    Confirm you're logged in to the correct account and role.
  </Step>

  <Step title="Check Role Permissions">
    Ask your Cloud Administrator to verify:

    * You have the correct role assigned
    * The role has the right permissions
    * You are in the correct AWS account
  </Step>

  <Step title="Try another profile">
    Switch to a profile with the correct permissions:

    ```bash theme={null}
    # Use admin profile for administrative tasks
    aws s3 ls --profile <project>-<account_name>-AdministratorAccess

    # Use read-only profile for viewing resources
    aws s3 ls --profile <project>-<account_name>-ReadOnlyAccess
    ```
  </Step>
</Steps>

## 4. Performance Issues

This section is for cases where authentication works but feels slow or requires frequent re-login.

### 4.1. Slow Authentication

**Symptoms:**

* You are asked to re-authenticate too often

**How to fix it:**

<AccordionGroup>
  <Accordion title="Reduce Token Refresh" icon="timer">
    ```bash theme={null}
    # Check token expiration
    aws configure export-credentials --profile <project>-<account_name> --format env

    # Login once for multiple operations
    aws sso login --profile <project>-<account_name>
    # You can now run multiple commands without re-authentication
    ```
  </Accordion>
</AccordionGroup>

# Debugging Tools and Commands

These commands help you inspect profiles, test authentication, and analyze logs.

<Tabs>
  <Tab title="Profile Validation">
    ```bash theme={null}
    # List all profiles
    aws configure list-profiles

    # Show profile configuration
    aws configure list --profile <project>-<account_name>

    # Test authentication
    aws sts get-caller-identity --profile <project>-<account_name>

    # Show current credentials
    aws configure export-credentials --profile <project>-<account_name>
    ```
  </Tab>

  <Tab title="Debug Mode">
    ```bash theme={null}
    # Enable debug logging
    aws s3 ls --debug --profile <project>-<account_name>

    # Check CLI version
    aws --version

    # Verbose output
    aws s3 ls --cli-read-timeout 60 --cli-connect-timeout 60 --profile <project>-<account_name>
    ```
  </Tab>

  <Tab title="Cache Information">
    ```bash theme={null}
    # Check SSO cache
    ls -la ~/.aws/sso/cache/

    # Show cache contents (be careful with sensitive data)
    find ~/.aws/sso/cache/ -name "*.json" -exec echo "File: {}" \; -exec jq '.expiresAt' {} \;

    # Clear cache
    rm -rf ~/.aws/sso/cache/*
    ```
  </Tab>
</Tabs>

# Getting Help

### Useful information for troubleshooting

* Profile name you're using
* Exact issue or error message (copy/paste)
* Command that failed
* AWS account and role
* Operating system and AWS CLI version
* Any recent configuration changes

## Additional Resources

**AWS Documentation:**

* [AWS CLI SSO Configuration](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html)
* [AWS SDK Documentation](https://docs.aws.amazon.com/)
* [AWS Identity Center User Guide](https://docs.aws.amazon.com/singlesignon/)

**Community:**

* AWS re:Post forums
* Stack Overflow (tag: aws-sso)
* AWS SDK GitHub repos

## Emergency Procedures

<Warning>
  **If you suspect compromised credentials:**

  1. **Immediately contact your Cloud Administrator**
  2. **Block the vulnerable user with Blocked User SCP**
  3. **Change your SSO password**
</Warning>