Troubleshoot Amazon Devices Builder Tools for AI-Powered Development

This page helps you resolve common issues when setting up and using Amazon Devices Builder Tools for AI-Powered Development, including connection errors (MCP error -32000: Connection closed), missing context documents, and skills that don't trigger. Each issue includes the problem description, likely causes, and step-by-step solutions.

For setup instructions, see Set Up Amazon Devices Builder Tools for AI-Powered Development.

Before you troubleshoot

Confirm Amazon Devices Builder Tools is running and connected to your AI agent. In your agent's chat, enter:

   List the tools provided by Amazon Devices Builder Tools

You should see a response that includes tools such as analyze_perfetto_traces, get_app_hot_functions, list_documents, read_asset, read_document, search_documentation, and symbolicate_acr.

You can also run the check-status command to verify your setup:

   npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest check-status

When fully configured, you see output similar to:

Agent                  │ Context Document         │ MCP Configuration
───────────────────────┼──────────────────────────┼──────────────────────────
Kiro                   │ ✅ v5.1                   │ ✅ Configured

📊 Summary:
   Total agents checked: 1
   ✅ Fully configured: 1

If the tools list appears and check-status shows your agent as fully configured, the MCP server is working. If not, continue to the issues in the following section.

Common issues

For most issues, start by running check-status from your project directory. It validates context documents (existence, version, corruption) and MCP configuration for all supported agents.

AI agent doesn't use Amazon Devices Builder Tools to answer Vega-related questions

Cause: The MCP server installation or configuration has an issue, or the AI agent requires a restart after configuration.

Solution:

1. Verify MCP server installation:

   Copy code Copied to clipboard.

   npx @amazon-devices/amazon-devices-buildertools-mcp@latest --help
   

   If the package is installed correctly, you see a help message listing available commands (init-context, check-status).

   If the package isn't installed, you see "command not found" or a module resolution error. Run the set-up command to install it.

2. Confirm that an amazon-devices-buildertools-mcp entry exists under mcpServers in your AI agent's settings file.
3. Restart your AI agent after configuration changes.

4. Verify the fix by asking an Amazon Devices-specific question.

   Example: "How do I build a Vega app?"

   If the agent responds with Amazon Devices-specific steps, the issue is resolved.

Error message says document isn't included in amazon-devices-buildertools-mcp version

Cause: The document name contains a typo, the document doesn't exist, or you have an outdated version of the MCP server.

Solution:

1. List available documents:

   Copy code Copied to clipboard.

   Show me all the documents in Amazon Devices Builder Tools
   

2. Compare the document name you used against the list returned in step 1. Verify the name exists and the spelling matches exactly.

3. Re-run init-context to refresh context documents. Using @latest in the npx command always fetches the newest release:

   Copy code Copied to clipboard.

   npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context
   

4. Retry the document request with the correct name. If the document loads, the issue is resolved.

AI agent provides generic responses, not Amazon Devices-specific guidance

Cause: Context initialization didn't complete, context files are missing, or the AI agent isn't recognizing the context files.

Solution:

1. Run check-status from your project directory (see Before you troubleshoot). If the output shows issues, follow the recommendations it provides.

2. If check-status shows context documents are missing or outdated, re-run init-context (see Get started).

3. Close your current chat conversation and start a new one.

4. Ask an Amazon Devices-specific question to confirm the agent provides relevant guidance.

   Example: "Can you list all documents related to feature development on Vega?"

   If the agent responds with Amazon Devices-specific guidance, the issue is resolved.

Agent Skills don't trigger automatically

Cause: Your AI agent requires context initialization to detect skills. Without proper setup, the agent can't recognize skill metadata.

Solution:

1. Run check-status from your project directory to validate your overall setup, including skill installation (see Before you troubleshoot).

2. If check-status reports issues, re-run init-context to ensure skills are installed (see Get started).

3. Verify that SKILL.md files exist in your agent's global skill directory. Common skill directory locations:

   AI Agent	Skill directory path
   Kiro	~/.kiro/skills/
   Cursor	~/.cursor/skills/ or .cursor/skills/ in your project root
   Claude Code	~/.claude/skills/

4. Restart your AI agent session.

   Skills trigger based on prompt matching. Use specific keywords related to the skill.

   Example: "Set up Vega SDK" for the amazon-devices-vega-setup-sdk skill".

5. If skills still don't trigger, list available skills first:

   Copy code Copied to clipboard.

   List all available Amazon Devices Builder Tools skills
   

   Then, reference the specific skill:

   Copy code Copied to clipboard.

   Use the amazon-devices-vega-build-and-run skill to help me deploy my app
   

   If the skill triggers and provides guided steps, the issue is resolved.

Unnecessary Agent Skills load automatically

Cause: The init-context command installs all available Agent Skills globally. You may want to remove specific skills that aren't relevant to your workflow.

Solution:

1. Locate the skill directory for your AI agent (see skill directory locations).

2. Delete the SKILL.md file for the skill you want to remove.

   For example, to remove the amazon-devices-vega-media-player skill:

   Copy code Copied to clipboard.

   rm ~/.kiro/skills/amazon-devices-vega-media-player/SKILL.md
   

3. Restart your AI agent session. The removed skill no longer triggers.

amazon-devices-buildertools-mcp fails to load

After adding the config, the IDE fails to initialize the MCP and displays:

MCP error -32000: Connection closed  

Cause: The package installation failed or there is a Node version mismatch.

Solution:

1. Verify the package runs outside the IDE:

   Copy code Copied to clipboard.

   npx @amazon-devices/amazon-devices-buildertools-mcp@latest --help  
   

   If you see a help message, the package is installed correctly — skip to step 3.

2. If the command fails, install the package globally:

   Copy code Copied to clipboard.

   npm install -g @amazon-devices/amazon-devices-buildertools-mcp@latest
   

3. Confirm the package appears under your current Node version:

   Copy code Copied to clipboard.

   npm list -g 
   

   Each Node version maintains its own global installations. For example, nvm use 20 && npm list -g shows a different list than nvm use 22 && npm list -g.

4. Close your current chat conversation and start a new one.

5. Ask your agent to list the available tools.

   Example: "What tools does Amazon Devices Builder Tools provide?"

   If the agent responds with the tools list, the issue is resolved.

amazon-devices-buildertools-mcp doesn't work with asdf

Cause: asdf creates a shell script wrapper instead of a direct node binary. The MCP server expects a real node binary, so the standard npx-based config works on CLI but fails in the IDE with MCP error -32000: Connection closed.

Solution:

1. Install the MCP:

   Copy code Copied to clipboard.

   npm install -g @amazon-devices/amazon-devices-buildertools-mcp@latest
   

2. Obtain path of node binary:

   Copy code Copied to clipboard.

   % asdf which node
   

   You see output similar to the following:

   ~/ASDF_DATA/installs/nodejs/22.20.0/bin/node
   

3. Obtain path of amazon-devices-buildertools-mcp binary:

   Copy code Copied to clipboard.

   % asdf which amazon-devices-buildertools-mcp
   

   You see output similar to the following:

   <>/ASDF_DATA/installs/nodejs/22.20.0/bin/amazon-devices-buildertools-mcp
   

   Note: Output for steps 2 and 3 differs based on your ASDF_DATA_DIR setting.

4. Update your AI agent's MCP settings file with the paths from steps 2 and 3. Replace the placeholder paths with your actual output:

   Copy code Copied to clipboard.

   "amazon-devices-buildertools-mcp-npx": {
       "type": "stdio",
       "command": "<>/ASDF_DATA/installs/nodejs/22.20.0/bin/node", // path copied from above
       "args": [
           "<>/ASDF_DATA/installs/nodejs/22.20.0/bin/amazon-devices-buildertools-mcp" // path copied from above
      ]
   },
   

   Note: Use the key name amazon-devices-buildertools-mcp-npx instead of amazon-devices-buildertools-mcp to avoid conflicts with the non-working npx-based config. Because of this alternate key, check-status reports "Not configured" even though the MCP is working correctly.

5. Close your current chat conversation and start a new one.

6. In the new chat, confirm the tools load by asking your agent to list the available tools.

   Example: "What tools does Amazon Devices Builder Tools provide?"

npm package page isn't available in Japanese

Cause: The npm package page for Amazon Devices Builder Tools is available in English only. The npm registry doesn't support Japanese locale.

Solution:

Use the setup instructions on the main setup page instead. This page is available in Japanese and contains all the installation and configuration steps you need. The npm commands (npx, npm install) work the same regardless of locale.

Gemini CLI doesn't load the steering document from the project directory

Cause: Gemini CLI has a known issue where it doesn't pick up the GEMINI.md steering document installed in your project directory. See google-gemini/gemini-cli for details.

Solution:

Copy the file to your home directory for automatic loading:

   cp GEMINI.md ~/.gemini/GEMINI.md

Alternatively, type read GEMINI.md in the Gemini CLI session to load it manually.

GitHub Copilot doesn't load the steering document

Cause: GitHub Copilot may not automatically load the AGENTS.md steering document in some configurations. This is a known issue. See community/discussions for details.

Solution:

Type read AGENTS.md in the Copilot chat session to load the context manually.

App migration workflows don't produce expected results

Cause: App migration workflows (App Porting) are in Beta and only support the following migration paths:

• Fire OS WebView app → Vega Web App
• Fire OS React Native app → VegaScript app
• Generic TV app → Vega app (with auto-detection of app type)

Migrations outside these paths, or complex migrations involving custom native modules, multi-activity architectures, or heavily customized Fire OS APIs, may not produce expected results.

Solution:

• Confirm your app matches one of the supported migration paths listed above.
• For complex migrations, manual migration steps may be required alongside the automated workflow.
• Re-run your migration prompt after confirming the path is supported.

If the workflow still produces unexpected output, provide feedback using the prompt "I want to provide feedback" in your AI agent's chat.

Related topics

• Set Up Amazon Devices Builder Tools for AI-Powered Development
• Amazon Devices Builder Tools ReadMe
• Amazon Developer Community

Last updated: May 20, 2026