Troubleshooting & FAQ
Common issues and frequently asked questions
Common issues and frequently asked questions
Pastoralist manages npm and Bun overrides, pnpm pnpm.overrides, and Yarn
resolutions by creating an appendix that documents why each override exists
and which packages depend on it.
Without Pastoralist, it's easy to lose track of why an override was added, which packages still need it, or whether it's safe to remove.
Yes. Pastoralist reads and writes the override field your package manager uses:
overridespnpm.overrides, or pnpm-workspace.yaml for pnpm 11+resolutionsPastoralist updates the configured manifest, override source, and appendix
target. --setup-hook opts into a postinstall script change. Review changes
with --dry-run; providers may still write caches.
Package manifests use two-space JSON. Security auto-fix creates a temporary backup before writing.
Use overrides for:
Problem: Pastoralist isn't removing overrides that seem unnecessary.
Solution: Cleanup requires --remove-unused. Preview it with
--remove-unused --dry-run. Active keep constraints and uncertain dependency
usage can prevent removal. Use debug mode to inspect the decision:
npx pastoralist --debugLook for output showing which packages require the override.
Problem: Pastoralist changes the formatting of my package.json.
Solution: Pastoralist rewrites package.json as two-space JSON. If you see unexpected changes:
.prettierrc or .editorconfig that might conflictProblem: My patch files aren't being tracked in the appendix.
Solution: Ensure patches follow the standard naming convention:
patches/├── package-name+1.0.0.patch # Correct├── [email protected] # Incorrect└── custom-patch.patch # Won't be detectedConfigure depPaths: "workspace" at the root, or use explicit manifest globs
to narrow the scan:
npx pastoralist --depPaths "packages/*/package.json" --debugnpm overrides belong in the root manifest. Moving them into workspace manifests does not make them package-specific; use root nested overrides to scope a transitive override to a parent.
Run Pastoralist locally, review the generated diff, and include the appendix with your dependency change:
npx pastoralistgit diff -- package.jsonFor external sources, include those files in the review as well. See GitHub Action for checks and maintenance PRs.
Enable debug mode for detailed information:
npx pastoralist --debugDebug output includes:
Pastoralist can't locate your package.json. Solutions:
--path to specify locationYour package.json has syntax errors. Validate with:
node -e 'JSON.parse(require("node:fs").readFileSync("package.json", "utf8"))'Confirm that the override is in the field or file used by your package manager.
For pnpm 11+, check pnpm-workspace.yaml. A project with no overrides does
not need an override appendix.
Run pastoralist regularly:
{ "scripts": { "postinstall": "pastoralist" }}package.json does not support comments. Add a ledger reason to record
why an override exists, or provide reasons with --promptForReasons:
{ "overrides": { "lodash": "4.17.21" }, "pastoralist": { "appendix": { "[email protected]": { "ledger": { "addedDate": "2026-05-30T00:00:00.000Z", "reason": "Keep until upstream adopts the required version.", "source": "manual" } } } }}Review potentially unused patch paths reported by Pastoralist. It does not delete patch files.
--debug flagWhen reporting issues, include:
If you're tracking overrides manually in docs or issue trackers, Pastoralist will:
pastoralist.appendix--remove-unusedExpanded entries include ledger.addedDate. With compactAppendix,
routine entries may contain only top-level addedDate. Reasons, security
data, patches, and keep constraints require expanded entries.
reviewBy is descriptive metadata; it does not expire a keep constraint.
Use until or untilVersion for expiry.
npx pastoralist --debugpatches/
├── package-name+1.0.0.patch # Correct
├── [email protected] # Incorrect
└── custom-patch.patch # Won't be detectednpx pastoralist --depPaths "packages/*/package.json" --debugnpx pastoralist
git diff -- package.jsonnpx pastoralist --debugnode -e 'JSON.parse(require("node:fs").readFileSync("package.json", "utf8"))'{
"scripts": {
"postinstall": "pastoralist"
}
}{
"overrides": {
"lodash": "4.17.21"
},
"pastoralist": {
"appendix": {
"[email protected]": {
"ledger": {
"addedDate": "2026-05-30T00:00:00.000Z",
"reason": "Keep until upstream adopts the required version.",
"source": "manual"
}
}
}
}
}