Troubleshooting

chain: command not found right after install?

The install script may add ~/.npm-global/bin to your shell profile. Existing terminal windows keep the old PATH until you reload:

• Open a new terminal tab or window, or
• Run source ~/.zshrc (bash: source ~/.bashrc or source ~/.bash_profile)

Then verify and continue:

npm install -g chain-hub fails with EACCES on macOS?

Node from nodejs.org often installs globals under /usr/local, which your user cannot write to. Do not use sudo npm install (it causes mixed ownership later).

Easiest fix: run the install script (same as Quickstart):

It installs chain-hub and, when needed, sets npm’s prefix to ~/.npm-global and adds it to your shell PATH.

Manual fix (if you prefer plain npm):

Check: npm config get prefix should show ~/.npm-global, and which chain should resolve after a new terminal.

chain runs the wrong binary? Check aliases first.

If you see an old alias (for example bun run …/Code/chain/cli/chain.ts after renaming or moving the monorepo), update CHAIN_HUB_REPO / the alias target to your current clone (see cli/README.md), remove the stale line from your shell profile, then run unalias chain and open a new terminal.

chain hub fails with Bun is not defined?

Global installs run the CLI under Node.js, but older chain-hub builds started the dashboard with Bun-only APIs (Bun.serve). Upgrade to chain-hub@0.4.5 or newer (requires that version on npm — same as any CLI upgrade).

Recommended — same as Quickstart; the script runs npm install -g chain-hub and fixes common macOS PATH / permission issues:

Open a new terminal if chain is not found after the script updates your shell profile.

Alternative if global npm already works on your machine:

You should see Running at http://127.0.0.1:… with no stack trace. Until 0.4.5 is available on npm, install Bun and run:

chain pro activate says “This license key could not be verified”?

From chain-hub@0.4.6 onward, testers only need the CHAIN-… key (no CHAIN_HUB_PRO_LICENSE_SECRET env var). Upgrade the CLI, then ask your maintainer for a new key from chain pro issue-key.

Maintainer (one machine):

Tester:

On older builds, keys only worked when both sides set the same CHAIN_HUB_PRO_LICENSE_SECRET — upgrade instead of sharing secrets in chat.

chain pro install-pack says “Activate Chain Hub Pro first”?

Purchase or beta approval only delivers the license key — the pack is a separate step. Activate with chain pro activate <key> or Settings → Pro in the hub, confirm with chain pro status, then run chain pro install-pack or Install Chain Hub Pro pack on the Dashboard.

Account magic link never arrives or sign-in loops back to the form?

See Account for the full sign-in flow. Quick checks:

• Check Junk or Spam for mail from licenses@chainhub.one (common on iCloud and Gmail for first-time senders).
• Open the link in the same browser you use for chainhub.one — cross-origin license URLs can drop session cookies after redirect.
• On staging, save Basic Auth credentials for the site host when prompted; the account UI uses a separate session header and does not replace browser Basic Auth.
• You can skip Account and activate locally: chain pro activate <key> or Settings → Pro in the hub.

Pro pack installed but skills missing in the editor?

Run chain setup after install, then reopen the editor. For GitHub delivery, ensure gh auth login or GITHUB_TOKEN is set; HTTPS delivery does not need GitHub access.

Skill doesn’t appear in your editor?

Check symlink health with chain status, then recreate links with chain setup. Reopen the editor afterward — some editors cache skill paths at startup. Also ensure the skill or the pack it belongs to has not been deactivated in the Dashboard (chain hub -> #discover or #skills). Deactivated assets are renamed to .deactivated-<slug> on disk and ignored by chain setup.

chain validate reports a nested or unknown layout?

Skills must use a flat layout — only skills/<slug>/SKILL.md is valid. Nested category folders are not supported. Move or flatten the directory.

ok   skills/debug/SKILL.md
bad  skills/utilities/debug/SKILL.md   (nested — not supported)

Skills disappeared after Syncthing or Dropbox sync?

Syncing a hub without .git/ can propagate deletions from a partial replica. Use a single writer for the hub, or exclude skills/ from bidirectional sync. Restore from backup or re-run chain add for registry sources.

GitHub sync setup fails in the hub?

Hub Set up GitHub sync requires the GitHub CLI (gh) on your PATH and a successful gh auth login. Alternatively, create a private repo on GitHub manually and run chain sync init <url> from the terminal. See Cloud Sync.

Private GitHub pack install fails?

Export a token or use the GitHub CLI:

Supported: GITHUB_TOKEN, GH_TOKEN, GITHUB_ACCESS_TOKEN, or gh auth token when gh is on your PATH.

Skill shows as “Other” but you expected Protected Core?

A user-side copy under skills/<slug>/ shadows the bundled core entry. Delete the copy (after backing up edits) and run chain init + chain setup to restore core behaviour.

Registry validate errors for unregistered folders?

Every directory under skills/ (except protected core slugs mirrored only in core/) must appear in skills-registry.yaml. Register personal skills under personal: or install via chain add so provenance is recorded.