AWS troubleshooting

Find the message or badge you’re seeing, then follow the fix. For setup steps, see Connect an AWS account.

During setup

“Waiting for AWS…” doesn’t finish

The stack hasn’t finished creating the role. Open the stack in CloudFormation and wait for CREATE_COMPLETE, then select Try again.

Alfe can’t use the role

Check the account ID or role ARN you entered. Also check that you created the stack from the link Alfe gave you, because that link carries the matching external ID. If you edited the stack’s parameters, launch it again from Alfe.

The setup link expired or was already used

Setup links expire after 24 hours and work once:

During setup — select Launch in AWS again for a fresh link, then update the stack with it.
For an existing role connection — select Re-issue link on the connection. Alfe opens an Update stack link with a new external ID. When the stack shows UPDATE_COMPLETE, select I’ve updated the stack so Alfe can re-check access. An active connection stays active throughout.

Alfe says the role doesn’t require the external ID

The role’s trust policy lets Alfe in without the external ID. Alfe refuses these roles, because anyone who learned the role ARN could reach your account through Alfe.

Update the trust policy to require sts:ExternalId, then try again. The CloudFormation template from Alfe already does this, so recreating the role from the setup link also fixes it.

Alfe says STS isn’t activated

AWS Security Token Service (STS) is turned off for your account in the region Alfe requests credentials from. In the IAM console, open Account settings and activate the inactive STS regional endpoints. Then try again.

Agents see the same message when they request credentials until STS is activated.

Alfe says there were too many attempts

Alfe limits how often AWS is called during setup and for each agent profile. The message tells you how long to wait. Wait that long, then try again.

Agents cache each session for up to an hour, so a healthy agent rarely hits the limit. If one does, look for a script that requests credentials in a tight loop.

The connection shows “Setup incomplete”

The account is verified, but no roles are saved yet, so agents can’t use it. Select Finish setup to choose roles, or disconnect it if you no longer need it.

AWS rejects the access keys

Check the access key ID and secret, and that the key is still Connected in IAM. Root account keys are never accepted; create an IAM user, or use the role method.

A profile name is already in use

Another AWS connection on the same agent already uses that profile name, so Alfe won’t save it. Profile names must be unique on each agent:

In the dashboard — edit the flagged profile names, then save again.
With alfe aws share — pass a different name with --as <NAME>.

AWS SSO and shared sessions

Your IAM Identity Center session ended, so agents can’t get credentials. If you made the connection, select Sign in again and approve the new code. Agents keep the same accounts and roles. Only the person who signed in sees Sign in again.

Alfe asked the wrong region for your IAM Identity Center. Check the SSO region: it must match the sso_region value for your profile in ~/.aws/config, not the region your resources run in. Also check the access portal URL.

The shared session expired

Shared credentials last only as long as the session you exported. The connection shows Expired, and agents are told to share again. Run aws sso login and alfe aws share again on your computer. To avoid this, add --watch so the session refreshes while your local sign-in lasts.

Another person already shares a session under this name

Someone else has shared their own AWS session with this agent under the same profile name. You can’t replace another person’s session. Share yours under a different name with --as <NAME>, or ask them to stop theirs with alfe aws share --stop.

`alfe aws share` asks you to confirm shared use

Other people can chat with the agent, so sharing needs your confirmation. In a terminal, answer y at the prompt. Without a terminal, re-run the command with --confirm-shared. Read When other people can use your access first.

`alfe aws share` says the AWS CLI is too old

alfe aws share needs AWS CLI v2.9 or later for aws configure export-credentials. Update the AWS CLI, then run the command again. Check your version with aws --version.

`alfe aws share` can’t export credentials

Your local AWS session has probably ended. Run aws sso login --profile <LOCAL_PROFILE>, then share again. If the command says the profile uses long-term access keys, use an SSO or role profile instead.

When agents use a profile

The agent is denied when it requests credentials

AWS refused to issue a session for the profile, so the AWS command fails before it runs. The agent reports the reason. Common causes:

The role, or its trust policy, was changed or deleted in AWS.
A chained role no longer trusts the connected identity.
STS isn’t activated in the region Alfe uses; see Alfe says STS isn’t activated.

For a role connection, select Re-issue link and run the update. That puts the Alfe role back to the shape Alfe expects. For a chained role, fix its trust policy in AWS.

AWS returns `AccessDenied`

The profile’s role doesn’t allow that action. The agent reports which profile and which action was denied. To fix it, either:

add the permission to the role’s policy in AWS, or
connect a role with a broader access level and select it in Manage roles.

Connect an AWS account: set up a connection and choose roles.
Revoke access: cut off an agent’s AWS access.