Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
221 lines (147 loc) · 5.93 KB

TROUBLESHOOTING.md

File metadata and controls

221 lines (147 loc) · 5.93 KB

Plugin Troubleshooting Guide

This guide provides troubleshooting steps for common issues when using plugins with various AI assistants.

Claude Code

Official Documentation

For general plugin troubleshooting, see the official documentation:

TUI (Terminal User Interface) Issues

If you're experiencing issues with the Claude Code TUI such as plugins not loading, skills not appearing, or marketplace data not refreshing:

Complete Reset Procedure

  1. Remove the markerplace

    • Within claude, run /plugin
    • Use your right arrow to navigate to the 'Marketplaces' tab
    • Select your marketplace
    • Press enter, then select 'Remove marketplace'

  2. Exit the current Claude Code session

    • Press Ctrl+C or type /exit to close the active session

  3. Close the terminal window

    • Completely close your terminal application (not just the tab)

  4. Clear the Claude Code cache

    # On macOS/Linux
rm -rf ~/.claude/plugins/cache

  5. Reset plugin state files Remove the information related to this marketplace/installed plugins from this marketplace in the state files:

    • ~/.claude/plugins/installed_plugins.json — which plugins are installed (version, install path, scope)
    • ~/.claude/plugins/known_marketplaces.json — which marketplaces are known (sources, URLs)

  6. Restart

    • Open a new terminal window
    • Run claude to start a fresh session

  7. Install

    • Within claude, run /plugin marketplace add awslabs/agent-plugins

Verification Steps

After resetting, verify your setup:

claude
#(run inside Claude Code the next commands)
# Check installed marketplaces
/plugin marketplace list

# Check installed plugins
/plugin list
# Then navigate to the "Installed" tab using your right arrow

# Check available skills
/skills

# Check available mcp servers
/mcp

Plugin Installation Issues

Marketplace Not Found

# Remove and re-add the marketplace
/plugin marketplace remove agent-plugins-for-aws
/plugin marketplace add awslabs/agent-plugins

Plugin Not Found in Marketplace

  1. Verify the marketplace was added correctly:

    /plugin marketplace list

  2. Check the marketplace repository is accessible:

  3. Reinstall the marketplace and plugin:

    /plugin marketplace remove agent-plugins-for-aws
/plugin marketplace add awslabs/agent-plugins
/plugin install deploy-on-aws@agent-plugins-for-aws

  4. Try the reset procedure

MCP Server Connection Issues

If MCP servers (like awspricing, awsknowledge, awsiac) fail to connect:

  1. Check MCP server logs:

    # Logs are typically in
~/.cache/claude-code/logs/

  2. Restart the servers

    # Run this within claude code
/plugin
# navigate to the installed tab, use your keyboard arrows to navigate to the plugin you are interested, then the mcp server
# Press space to toggle the mcp server, then toggle again to restart

Skill Not Auto-Triggering

If a skill isn't being invoked when expected:

  1. Verify the skill is loaded:

    /skills

    Look for deploy-on-aws:deploy in the list

  2. Check your phrasing:

    • Skills auto-trigger based on intent matching
    • Try explicit phrases like "deploy this to AWS" or "host on AWS"
    • Avoid ambiguous requests like "help me with AWS"

  3. Manually invoke the skill:

    /deploy

  4. Check plugin installation:

    /plugin list

    Ensure deploy-on-aws shows as installed

Getting Help

If issues persist:

  1. Check GitHub Issues:

  2. Enable Debug Mode:

    claude --verbose

  3. Collect Information:

    • Claude Code version: claude --version
    • Plugin version: /plugin list
    • Error messages from logs: ~/.cache/claude-code/logs/
    • Verify the scope of installation

  4. Create a New Issue:

CI / GitHub Actions

Re-running Failed Jobs

GitHub Actions workflows can occasionally fail due to intermittent issues (network timeouts, flaky upstream services, etc.). If you believe a failure is not related to your changes:

Via the GitHub UI

  1. Open the failed check from your pull request's Checks tab.
  2. Click Re-run failed jobs.

See Re-running workflows and jobs for details.

Via the gh CLI

See Re-run failed jobs from a workflow run.

RUN_ID=0

gh api \
  --method POST \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /repos/awslabs/agent-plugins/actions/runs/${RUN_ID:-0}/rerun-failed-jobs

Replace RUN_ID with the workflow run ID from your pull request's Checks tab or from gh run list --branch <your-branch>.

Required Permissions

  • Repository collaborators (write access) can re-run workflows directly.
  • Fork contributors cannot re-run workflows on the upstream repo. Ask a maintainer to re-run the failed jobs, or push an empty commit (git commit --allow-empty -m "retry CI") to trigger a fresh run.

Other AI Assistants

Support for additional AI assistants will be added here as the plugin system expands.

Last Updated: 2026-02-09