Troubleshooting the Category SDK

The commands shown in this guide use alexa-ai and alexa-ai-user as AWS profile names. These refer to the profiles you configured during the onboarding steps:

alexa-ai-user is the base credential profile (IAM User keys)
alexa-ai is the role assumption profile (AddOn3PDeveloperToolsRead). If you used different profile names during setup, replace accordingly.

`alexa-ai new` or `alexa-ai test` Fails with git clone error

Symptom

fatal: unable to access 'https://git-codecommit.us-west-2.amazonaws.com/v1/repos/...': The requested URL returned error: 403

If alexa-ai new or alexa-ai test commands fail with a Git clone error, follow these steps:

Verify your IAM user credentials are valid.
aws sts get-caller-identity --profile alexa-ai-user
If this fails → your Access Key ID or Secret Access Key is invalid or rotated. Generate new keys in your AWS IAM console.
Verify role assumption works
aws sts get-caller-identity --profile alexa-ai
If this fails → check that your IAM user has the sts:AssumeRole policy attached.

Clear cached credentials macOS:

 printf "host=git-codecommit.us-west-2.amazonaws.com\nprotocol=https\n\n" | git credential-osxkeychain erase

Ubuntu/Linux (libsecret):

 printf "protocol=https\nhost=git-codecommit.us-west-2.amazonaws.com\n" | git-credential-libsecret erase

Ubuntu/Linux (store — plaintext file):

 sed -i '/git-codecommit.us-west-2.amazonaws.com/d' ~/.git-credentials

Ubuntu/Linux (cache — in-memory):

 git credential-cache exit

Verify git credential helper is configured.
git config --global --get "credential.https://git-codecommit.us-west-2.amazonaws.com.helper"
Expected: !aws codecommit credential-helper --profile alexa-ai $@

Test git access manually.

 git ls-remote https://git-codecommit.us-west-2.amazonaws.com/v1/repos/category-restaurant-reservation-template-typescript

Once the above succeeds, retry the alexa-ai new or alexa-ai test command.

npm install fails with 401 Unauthorized

Symptom:

npm error 401 Unauthorized - GET https://alexa-ai-372468808636.d.codeartifact.us-west-2.amazonaws.com/...

Steps:

Re-authenticate (CodeArtifact token expires every 12 hours):

 aws codeartifact login \
   --tool npm \
   --domain alexa-ai \
   --repository npm-packages \
   --domain-owner 372468808636 \
   --region us-west-2 \
   --namespace @alexa-ai \
   --profile alexa-ai

If the issue persists, delete the @alexa-ai entries from ~/.npmrc: macOS:
sed -i '' '/@alexa-ai/d' ~/.npmrc
Ubuntu/Linux:
sed -i '/@alexa-ai/d' ~/.npmrc
Re-run the login command from step 1 to regenerate fresh entries.
Verify the registry is configured correctly:
npm config get @alexa-ai:registry
Expected: https://alexa-ai-372468808636.d.codeartifact.us-west-2.amazonaws.com/npm/npm-packages/

CDK deploy fails with credential errors

Symptom:

Unable to resolve AWS account to use

Fix: Verify default profile credentials:

aws sts get-caller-identity

If this fails, re-run aws configure with your Access Key ID and Secret Access Key (see onboarding Step 5).

Credentials stopped working after a while (403 or 401 on commands that worked before)

Symptom Commands that worked earlier (alexa-ai, git, or npm) start failing with 403 (Git/CodeCommit) or 401 (npm). The failures often start after a few hours away from your machine. Cause Your credentials are temporary. The credentials from assuming the AddOn3PDeveloperToolsRead role are short-lived (up to 12 hours), and the CodeArtifact npm token also expires every 12 hours. When they lapse, Alexa AI CLI, Git, and npm all return authorization errors until you refresh. Fix

Refresh the credentials for your alexa-ai role profile using the same command you ran during onboarding, then confirm:
aws sts get-caller-identity --profile alexa-ai
A successful response shows an assumed-role ARN ending in .../AddOn3PDeveloperToolsRead/....

Refresh the CodeArtifact npm token:

aws codeartifact login \
  --tool npm \
  --domain alexa-ai \
  --repository npm-packages \
  --domain-owner 372468808636 \
  --region us-west-2 \
  --namespace @alexa-ai \
  --profile alexa-ai

If Git still returns 403 after refreshing, clear the cached credential for the repository host (see the git clone section, step 3) and retry.

Tip: Refresh the CodeArtifact token at the start of each working session, because it lasts 12 hours.

Which IP addresses does Alexa use? Can I allowlist them?

Alexa doesn’t publish a fixed set of inbound IP ranges, and IP allowlisting isn’t the supported way to secure your add-on endpoint. Instead, verify that Alexa signed each request. For details, see Secure your add-on endpoint.

4xx error thrown by API Gateway

Symptom When testing, you get a 4xx error from API Gateway. Fix: Ensure you haven’t set ALEXA_ADDON_UNDER_TEST in the CDK stack. This enables basic auth where Alexa sent requests are signed using Private Key.

Get Started

Build with the MCP Toolkit

Build with the Category SDK

Testing

Certification

Reference

`alexa-ai new` or `alexa-ai test` Fails with git clone error

Symptom

npm install fails with 401 Unauthorized

CDK deploy fails with credential errors

Credentials stopped working after a while (403 or 401 on commands that worked before)

Which IP addresses does Alexa use? Can I allowlist them?

4xx error thrown by API Gateway

​alexa-ai new or alexa-ai test Fails with git clone error

​Symptom

​npm install fails with 401 Unauthorized

​CDK deploy fails with credential errors

​Credentials stopped working after a while (403 or 401 on commands that worked before)

​Which IP addresses does Alexa use? Can I allowlist them?

​4xx error thrown by API Gateway

`alexa-ai new` or `alexa-ai test` Fails with git clone error

Symptom

npm install fails with 401 Unauthorized

CDK deploy fails with credential errors

Credentials stopped working after a while (403 or 401 on commands that worked before)

Which IP addresses does Alexa use? Can I allowlist them?

4xx error thrown by API Gateway