Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases

Console

as

Get Started
Design and Develop
Publish
Reference
Support
Skip to main content
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:
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:
When fully configured, you see output similar to:
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. 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:
    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:
  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:
  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:
  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:
    Then, reference the specific skill:
    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:
  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:
Cause: The package installation failed or there is a Node version mismatch. Solution:
  1. Verify the package runs outside the IDE:
    If you see a help message, the package is installed correctly — skip to step 3.
  2. If the command fails, install the package globally:
  3. Confirm the package appears under your current Node version:
    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:
  2. Obtain path of node binary:
    You see output similar to the following:
  3. Obtain path of amazon-devices-buildertools-mcp binary:
    You see output similar to the following:
  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:
  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:
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.
Last modified on May 20, 2026