iClaude
Tutorial · 7 of 8

When something breaks

A short catalog of the errors we see most often. Each one tells you what's actually wrong and the one command that fixes it.

6 min read

Quick index

command not found: npx

Your shell can't find npx because Node.js isn't installed — or it's installed but in a folder your shell doesn't know about.

Fix: install Node.js (see /docs/tutorials/install-node), then close every terminal window and open a fresh one. The PATH only refreshes for new terminals.

terminal
$ node --version
$ npx --version

If both print versions, you're good.

EACCES: permission denied

npm is trying to write to a folder owned by root. This usually means you ran sudo npm install at some point in the past and permissions got tangled.

The right fix (changes npm to install to your home folder, no sudo ever needed):

terminal
$ mkdir -p ~/.npm-global
$ npm config set prefix '~/.npm-global'
$ echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
$ source ~/.zshrc

Use ~/.bashrc instead of ~/.zshrc if you use bash. After this, re-run the install.

Error: skill "xyz" not found

The slug you passed doesn't exist in the catalog. Three common reasons:

  • Typo — slugs are hyphen-separated and case-sensitive (pdf-reader, not pdfreader or PDF-Reader).
  • Renamed skill — search the catalog at iclaude.io/skills to get the current slug.
  • Stale cache — flush it and retry:
terminal
$ npx iclaude cache clear

Skill installed but doesn't appear in my AI tool

You forgot to fully quit and restart the AI tool. The skill list only loads at app startup.

  • Claude Desktop: right-click the dock/tray icon → Quit. Closing the window doesn't count.
  • Cursor: File → Quit Cursor (Cmd/Ctrl + Q).
  • ChatGPT: toggle the connector off and back on in Settings → Connectors.
  • n8n: restart the n8n process or container.

Still not showing? Run the doctor:

terminal
$ npx iclaude doctor

It prints every install, which stack it's wired into, and which config file got written. Often you'll spot "Wrote to Cursor" when you wanted Claude.

connection refused or skill timeout

The skill started, but something it tries to reach isn't there. Common cases:

  • Local database skill: Postgres/MySQL isn't actually running. Start it.
  • API skill: missing or wrong API key. Open the skill's config file — iClaude points to it after install — and check the env block.
  • Remote MCP skill: the upstream server is down. Check status.iclaude.io.
  • Firewall / corporate network: the skill can't reach the internet. Ask IT to allow the domain from the skill page.

For raw logs, run the skill manually from a terminal and watch the output. The doctor command prints the exact command to use:

terminal
$ npx iclaude doctor --skill pdf-reader --debug

iClaude installed into the wrong AI tool

The auto-detector guessed wrong (it picks the first AI tool it finds installed). Force a target:

terminal
# Remove the bad install
$ npx iclaude uninstall pdf-reader

# Install with the right stack
$ npx iclaude install pdf-reader --stack claude
# or: --stack cursor, --stack n8n, --stack chatgpt

How to uninstall a skill

terminal
$ npx iclaude uninstall pdf-reader

Restart your AI tool. Done. iClaude removes the entry from the right config file and leaves everything else intact.

To wipe every iClaude skill at once:

terminal
$ npx iclaude reset

It asks for confirmation. This only touches skills installed through iClaude — any skills you added by hand to the config files stay where they are.

How to update a skill

terminal
# One specific skill
$ npx iclaude update pdf-reader

# Every installed skill
$ npx iclaude update --all

Restart the AI tool afterwards. iClaude keeps a record of the version it installed, so the doctor command will flag skills that have a newer release available.

Still stuck?

Open an issue with the output of npx iclaude doctor at github.com/iclaude-io/cli/issues. Include your OS, Node version, and which AI tool you're using.