Troubleshooting

MODULE_NOT_FOUND after installing a Node package

The package was published with unbundled external dependencies. When the MCP server starts, Node tries to require() packages that aren't shipped inside the tarball.

# error from the MCP runtime:
# Error: Cannot find module '@octokit/rest'

Fix (as the publisher): bundle your entry file before publishing.

$ esbuild src/index.ts --bundle --platform=node --outfile=dist/index.js

Fix (as the user): install dependencies manually in the package directory.

$ cd ~/.syphon/packages/github-tools
$ npm install

Author mismatch error

$ syphon publish
# ✗ manifest author 'Alice' does not match logged-in user 'alice123'

The author field in syphon.json must match your account's username or display_name. Run syphon whoami to see what the registry knows you as:

$ syphon whoami
# alice123 (alice@example.com) — 3 packages

Update syphon.json to use alice123, or update your display_name in your account settings to match what you want to use.

Publish blocked by secret scan

$ syphon publish
# ✗ Refusing to publish: secrets detected.
#   .env:3  AWS_SECRET_KEY  AKIAIOSFODNN7EXAMPLE

A hard-block pattern was found in a file that would be included in the tarball.

Option 1 — add the file to .syphonignore:

.env
*.pem
secrets/

Option 2 — remove the credential from the file if it shouldn't be there at all.

No signing key found

$ syphon publish
# ✗ No signing key found. Run 'syphon login' to generate one.

The signing key at ~/.syphon/keys/signing.key is missing. This happens if you logged in on a different machine, or manually deleted the file.

# re-login to generate a new key and register the public half
$ syphon logout
$ syphon login

Bad signature on install

$ syphon install github-tools
# ✗ Signature verification failed for github-tools@1.0.0

The tarball bytes don't match the signature stored in the registry. This shouldn't happen in normal operation — if it does, the package may have been tampered with or the registry has a data integrity issue. Do not install the package and report it to the publisher.

If you're the publisher and you get this after rotating your key, the registry still has your old public key for previously-published versions. Old versions are signed with the old key and will fail if you've rotated. Re-publish with a new version number.

Token expired or invalid

$ syphon publish
# ✗ Unauthorized: token expired or invalid

$ syphon logout
$ syphon login

For CI tokens, create a new one with a longer expiry:

$ syphon token create --name ci-deploy --expires 365 --scope publish

Rate limit exceeded (429)

$ syphon search tools
# ✗ Rate limit exceeded. Retry after 47s.

Unauthenticated requests are limited to 100/hour. Log in to get 1,000/hour:

$ syphon login

Publish operations are limited to 10/hour regardless of auth. See rate limits for the full table.

Invalid framework value in syphon.json

$ syphon publish
# ✗ unknown variant 'crewai', expected one of 'claude-code', 'cursor', 'crew-ai', ...

Framework values must be kebab-case. The correct value is crew-ai, not crewai. Full list of valid values:

"frameworks": ["claude-code", "claude-desktop", "cursor", "windsurf", "gemini-cli", "cline", "codex", "zed", "continue", "vscode-mcp", "goose", "kiro", "augment", "langchain", "crew-ai", "openai-agents", "generic"]

Entry file not found

$ syphon pack
# ✗ Entry file not found: dist/index.js
#   Build your project first: npm run build

The file declared in syphon.json's entry doesn't exist. Build your project first:

$ npm run build
$ syphon pack

If your entry is in src/ (not a compiled output), Syphon will warn you. Update the entry field to point to your built output directory.

Network errors

$ syphon search tools
# ✗ network error: error sending request for url (http://localhost:3001/v1/packages)

If the CLI is pointing at localhost (dev mode), start the API server:

$ cd api && bun dev

For production connectivity issues, check your network and confirm the registry is reachable:

$ curl https://syphon-api.vercel.app/v1/health

Override the registry URL with --registry <url> if you're using a self-hosted instance.