Skip to content
Starter $4 · soon
Menu
Docs: Troubleshooting

Claude Code troubleshooting: fixes for real errors

Most problems have a short fix: restart Claude Code in the right folder, approve the project's MCP server, quote paths that contain spaces, and wait out usage limits instead of fighting them. Find your error below. Claude Code behaviour on this page was checked against Anthropic's Claude Code docs on 2026-10-16.

Claude Code cannot find a skill

Usually Claude Code was opened in a different folder, or the skills folder was created after the session started.

  1. Open Claude Code in your project folder. Project skills in .claude/skills/ load only for sessions in that project.
  2. Restart or reload. Claude Code picks up edits to existing skills live, but if the .claude/skills folder didn't exist when the session started, run /reload-skills or restart in a new session.
  3. Ask Claude "What skills are available?" to see what actually loaded.
  4. Check the file. Each skill needs SKILL.md with --- on the very first line. Run claude --debug to see parse errors.

Note: Agent2Ship's 13 skills are hidden from the / menu on purpose. Not seeing them there is normal; you run the /a2s-* commands and the agents load the skills.

Claude Code MCP not working or not showing

A new MCP server shows up only after a restart, and a project-scoped server waits for your approval.

  1. Restart Claude Code in the project folder after adding the server.
  2. Approve it. For security, Claude Code asks before using servers from a project's .mcp.json. If you missed or declined the prompt, reset your choices and restart:
(terminal)
claude mcp reset-project-choices
  1. Check its status. claude mcp list shows each server as connected, pending approval, or failed to connect. Inside Claude Code, /mcp shows the same.
(terminal)
claude mcp list
  1. See why it failed. claude mcp get <name> prints the issue for a server that failed to connect.

Agent2Ship adds the Astro docs MCP at project scope, which also avoids path-case issues on Windows. If it still won't load, /a2s-build warns you and continues with Astro's official docs on the web.

Claude Code usage limit reached

Wait for the reset Claude Code shows, then run the same command again. There's no safe shortcut, and we don't recommend workarounds.

  • The design step resumes from DESIGN-PROGRESS.md, so you don't lose finished work.
  • To use less next time: start fresh sessions for big steps, and let the Sonnet-based research agents do the research. See tips for saving tokens.

Error: Cannot find module ... install.mjs

Node prints this when the path you gave it doesn't point to a real file. A real error from building this kit. The usual causes:

  • A path with spaces, without quotes. C:\Users\Your Name\... gets cut at the space. Wrap the whole path in double quotes.
  • The wrong folder. Unzipping can create a folder inside a folder (for example agent2ship\agent2ship\install.mjs). Open the folder and check where install.mjs really is.
  • A typo in the path. Copy the folder path from File Explorer or Finder instead of typing it.

Check the file exists before running the installer (Windows PowerShell):

(Windows PowerShell)
Test-Path "C:\Users\You\Downloads\agent2ship\install.mjs"

True means the path is right. Then run the install command from getting started.

Still stuck?

Send a DM on X with the exact error text and your operating system. Details on the contact page.