Claude Code awsAuthRefresh Hangs? Fix AWS SSO Proxy Startup

If Claude Code never reaches a prompt after [API:auth] AWS credential resolve start, and you use awsAuthRefresh with AWS SSO behind a corporate proxy, stop retrying startup. Remove awsAuthRefresh from ~/.claude/settings.json, run the SSO login manually, verify the active identity, and then relaunch Claude Code.

Anthropic's official Bedrock guide already recommends this manual-login pattern when a VPN or TLS inspection proxy interferes with automatic SSO. A fresh upstream report narrows one current failure to Claude Code 2.1.223 and 2.1.224 attempting an AWS SSO OIDC connection outside the configured HTTPS proxy. Treat that report as a regression signal, not a confirmed maintainer diagnosis.

The Safe Fix in 60 Seconds

1. Stop the hanging Claude Code process with Ctrl-C.

2. Back up ~/.claude/settings.json.

3. Remove only the awsAuthRefresh property from that file.

4. Run aws sso login --profile my-sso-profile in the same shell.

5. Confirm the session with aws sts get-caller-identity --profile my-sso-profile.

6. Start Claude Code again.

Success means the AWS CLI completes its SSO flow, get-caller-identity returns the expected account and ARN, and Claude Code reaches a prompt without pausing at credential resolution. You will need to repeat the manual SSO login when the session expires until automatic refresh is safe to restore.

Match the awsAuthRefresh Proxy Hang First

Use this guide when all of these are true:

• Claude Code uses Amazon Bedrock with an AWS SSO profile.

• ~/.claude/settings.json contains an awsAuthRefresh command.

• Your network requires HTTPS_PROXY or https_proxy for internet access.

• claude --debug stops after [API:auth] AWS credential resolve start with no completion message.

• Running the SSO command manually can still reach the browser or device-code flow through the proxy.

The current report reproduced the hang on Windows and Linux behind the same corporate proxy. It identified 2.1.187 as the last working release and reproduced the failure on 2.1.223 and 2.1.224. Those version details belong to that report; they do not prove that every startup hang on those versions has the same cause.

This guide does not fit when the AWS CLI itself cannot log in, when Claude Code shows a normal expired-credential message, or when you do not use Bedrock. If an API key is taking precedence over your Claude subscription, use the Claude Code API billing diagnosis instead.

Back Up the Settings File

On macOS, Linux, or Git Bash, make a local backup:

cp "$HOME/.claude/settings.json" "$HOME/.claude/settings.json.awsauthrefresh-backup"

In PowerShell, use:

Copy-Item "$HOME\.claude\settings.json" "$HOME\.claude\settings.json.awsauthrefresh-backup"

Keep the backup local. A Claude Code settings file may contain paths, provider configuration, or other environment-specific details that should not be pasted into a public issue.

Remove Only awsAuthRefresh

Open ~/.claude/settings.json and remove the awsAuthRefresh property while preserving every unrelated setting.

Before:

{
  "awsAuthRefresh": "aws sso login --profile my-sso-profile"
}

After:

{}

If the file has other properties, preserve them and keep the JSON commas valid. Do not delete the whole settings file, clear ~/.aws, or replace the command with an invented proxy wrapper.

The current reporter found that a one-off --settings override with awsAuthRefresh set to false did not suppress the startup check. Editing the effective user settings is the more verifiable workaround. If Claude Code appears to ignore the edit, review the Claude Code settings precedence checks before changing anything else.

Log In to AWS SSO Manually

Run the same profile outside Claude Code:

aws sso login --profile my-sso-profile

Complete the browser or device-code flow. The AWS CLI sso login reference documents this command and its profile option.

Then verify the credentials:

aws sts get-caller-identity --profile my-sso-profile

The AWS STS reference explains the returned account, user ID, and ARN. Confirm that they belong to the expected environment before starting an agent that can change infrastructure.

If either AWS command hangs, stop. The automatic Claude Code refresh is no longer the only failing boundary. Diagnose the AWS CLI, proxy, SSO configuration, and corporate network with your administrator before continuing.

Relaunch Claude Code Through the Same Proxy

Keep the approved proxy environment unchanged and launch:

claude --debug

The expected result is that credential resolution completes and the prompt appears. Once it does, exit debug mode and work normally.

Do not work around the proxy by disabling TLS verification, bypassing the corporate egress policy, or moving credentials into plaintext environment files. Do not post raw debug logs without reviewing them for account IDs, local paths, SSO URLs, and other environment details.

Why Manual SSO Works

The official Claude Code Bedrock guide says awsAuthRefresh runs when Claude Code considers AWS credentials expired or receives a credential error. It also advises removing awsAuthRefresh and running aws sso login manually when VPNs or TLS inspection proxies disrupt automatic SSO.

The August 7 report adds a more specific observation: in the affected releases, the reporter saw the AWS SSO OIDC validation path attempt direct internet connections instead of the configured HTTPS proxy. A network that silently drops direct egress can leave that connection waiting without an immediate error.

Removing awsAuthRefresh skips that automatic startup path. The AWS CLI then owns the interactive login, and Claude Code starts with credentials that have already been validated. This is a reversible operating procedure, not a permanent upstream fix.

Common Fixes That Do Not Match This Failure

Avoid these detours:

• Repeatedly relaunching Claude Code leaves the same startup condition in place.

• Setting unrelated proxy variables does not prove the AWS SSO OIDC client uses them.

• Unsetting AWS_PROFILE may only move the failed lookup to a default profile or region.

• Deleting AWS SSO cache files discards useful state and does not repair proxy routing.

• Disabling certificate verification weakens security and does not make direct egress compliant.

• Pinning an older Claude Code release can reduce exposure temporarily, but manual SSO is the narrower workaround supported by current official guidance.

If manual SSO succeeds but Claude Code still hangs after awsAuthRefresh is removed, capture the version, operating system, shell, provider, sanitized last debug line, and whether get-caller-identity succeeds. Add that evidence to the matching upstream issue only when the symptoms align.

Restore Automatic Refresh Carefully

Watch the issue and Claude Code release notes. After an upstream fix is documented:

1. Update Claude Code on one test machine.

2. Preserve the working settings backup.

3. Restore the original awsAuthRefresh property.

4. Test on the corporate network with a non-production profile.

5. Confirm both startup validation and an expired-session refresh complete through the approved proxy.

Keep manual SSO if either test hangs. A version number alone is not a sufficient recovery signal.

Monitor the Regression With a Read-Only Action

Aident Loadout can check the upstream report without granting the agent permission to change GitHub. Give Claude Code the exact installation instruction:

Follow https://aident.ai/SETUP.md

Then use this prompt:

Check my Aident Loadout account authentication and Vault status. Search the staging capability catalog for a connected read-only GitHub issue Action, inspect its current schema, and preflight it. If the estimate is free, return only the state, updated time, title, reaction count, and URL for anthropics/claude-code issue 84878. Do not comment, edit, close, label, publish, install, change files, start OAuth, or request a GitHub token.

Success is measurable: one current issue record is returned, the receipt shows a read-only GitHub operation, and no GitHub write occurs. Set up Aident Loadout and monitor the AWS SSO proxy regression.

Sources

• Claude Code issue 84878: awsAuthRefresh startup pre-check hangs behind a proxy

• Official Claude Code Amazon Bedrock guide

• Official Claude Code settings reference

• AWS CLI sso login reference

• AWS STS get-caller-identity reference

• Official Claude Code release notes

Refresh this guide when issue 84878 changes state, the Claude Code release notes name the proxy regression, or a current release passes startup and expired-session refresh on the affected corporate network.