Skip to content

troubleshooting.md

Latest commit

 

History

History
111 lines (73 loc) · 3.26 KB

troubleshooting.md

File metadata and controls

111 lines (73 loc) · 3.26 KB

Troubleshooting

Exit codes

Situation Exit code
Prerequisite failure (no Next.js or no .git) 1
Module catalog / install failure 1
Unknown command 1
add / update with no pharn.config.json 1
User cancel at summary, or overwrite declined 0
Successful install 0

Prerequisites failed

Next.js not found

✗ Next.js not found.
  Run: npx create-next-app@latest
  Then re-run: npx pharn init

Ensure next appears in package.json dependencies or devDependencies. Exits with code 1.

Git not found

The CLI message says "git not found" but the check is for a .git directory, not the git binary:

✗ git not found.
  Run: git init && git add -A && git commit -m 'init'
  Then re-run: npx pharn init

Exits with code 1.

Monorepos / workspaces

pharn init checks the current directory for both package.json (with next) and a .git directory, and installs .claude/ there. It does not walk up to a workspace root or into workspace packages. In a monorepo, run it from the directory that contains both the Next.js package.json and .git — e.g. the app package if it has its own git, otherwise the repo root only works when next is in the root package.json. Split layouts (.git at the root, next in apps/web/package.json) are unsupported in v1.

Fresh-project warnings

Not errors. Confirm to continue or cancel to exit cleanly (code 0).

Checks run in order; only the first matching rule applies:

Warning Cause
Significant history 6+ commits on HEAD (stops here; no 2+ warning)
Existing commits 2–5 commits
Customized scaffold 0–1 commits but > 3 unrecognized files

Module catalog could not be loaded

Symptoms:

  • Spinner stops with "Failed to load module catalog"
  • Message references github.com/pharn-dev/pharn-oss
  • Exit code 1

The wizard fetches manifest.json from raw.githubusercontent.com/pharn-dev/pharn-oss/main/manifest.json. Check network access to GitHub and that the repo is reachable.

Install failed

Symptoms:

  • Spinner stops with "Failed to install skills"
  • Exit code 1

Causes include a degit clone failure (network/GitHub), a module declaring an installs path it doesn't ship, or an unknown constitution variant. Set PHARN_DEBUG=1 and re-run for the full stack trace:

PHARN_DEBUG=1 npx pharn init

Overwrite declined

If you decline overwriting pharn.config.json, the wizard cancels with exit 0 and nothing is fetched.

add / update say to run init first

No pharn.config.json found. Run `pharn init` first.

Both commands operate on an already-installed project. Run pharn init to create pharn.config.json.

Unknown command

Unknown command: ...

Run pharn --help. Valid commands: init, add, update.

Local development issues

Problem Fix
pharn not found after editing CLI npm run build:install-local from pharn-cli/
Type errors in tests npm run typecheck
Stale dist npm run build

See Contributing.

Related