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 forget 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.overridesresolutionsPastoralist is designed to keep changes reviewable:
pastoralist section of package.jsonpackage.json output to two-space JSONUse overrides for:
Problem: Pastoralist isn't removing overrides that seem unnecessary.
Solution: The override might still be needed by a transitive dependency. Run with debug mode to see why:
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 detectedProblem: Pastoralist takes a long time to run.
Solution: For large monorepos:
--ignore to skip unnecessary directories# Instead ofpastoralist --depPaths "**/package.json" # Tryfind . -name "package.json" -not -path "*/node_modules/*" | \ xargs -P 4 -I {} npx pastoralist --path {}Problem: Different packages in my monorepo need different versions.
Solution: Use package-specific overrides:
Root package.json can hold shared security patches:
{ "overrides": { "minimist": "1.2.8" }}Packages can hold their own compatibility requirements:
{ "overrides": { "react": "17.0.2" }}Problem: CI fails saying package.json was modified.
Solution: Run pastoralist locally and commit the changes:
npx pastoralistgit add package.jsongit commit -m "Update override appendix"Then add to your CI check:
- run: npx pastoralist- run: git diff --exit-code package.jsonEnable 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:
npx json package.jsonThis is normal if you don't have any overrides. Pastoralist will:
Run pastoralist regularly:
{ "scripts": { "postinstall": "pastoralist" }}package.json does not support comments. Every appendix entry has a ledger;
add a reason to it (or provide manual reasons when you generate the appendix):
{ "overrides": { "lodash": "4.17.21" }, "pastoralist": { "appendix": { "[email protected]": { "ledger": { "addedDate": "2026-05-30T00:00:00.000Z", "reason": "CVE-2021-12345 fix", "source": "manual" } } } }}When you see this warning:
🐑 Found potentially unused patch files: - patches/old-package+1.0.0.patchReview and remove unused patches to keep your repo clean.
--debug flagWhen reporting issues, include:
If you're tracking overrides manually in docs or issue trackers, Pastoralist will:
pastoralist.appendix--remove-unusedTo understand why an override is needed:
// debug-override.jsimport { resolveJSON, update } from "pastoralist"; const path = "./package.json";const config = resolveJSON(path); if (config) { update({ config, debug: true, path });} // Check the debug output for dependency paths// analyze-appendix.jsimport fs from "fs"; const pkg = JSON.parse(fs.readFileSync("./package.json", "utf-8"));const appendix = pkg.pastoralist?.appendix || {}; console.log("Override Report:");Object.entries(appendix).forEach(([override, info]) => { console.log(`\n${override}:`); console.log(" Dependents:", Object.keys(info.dependents || {})); console.log(" Patches:", info.patches || "none");});npx pastoralist --debugpatches/
├── package-name+1.0.0.patch # Correct
├── [email protected] # Incorrect
└── custom-patch.patch # Won't be detected# Instead of
pastoralist --depPaths "**/package.json"
# Try
find . -name "package.json" -not -path "*/node_modules/*" | \
xargs -P 4 -I {} npx pastoralist --path {}{
"overrides": {
"minimist": "1.2.8"
}
}{
"overrides": {
"react": "17.0.2"
}
}npx pastoralist
git add package.json
git commit -m "Update override appendix"- run: npx pastoralist
- run: git diff --exit-code package.jsonnpx pastoralist --debugnpx json package.json{
"scripts": {
"postinstall": "pastoralist"
}
}{
"overrides": {
"lodash": "4.17.21"
},
"pastoralist": {
"appendix": {
"[email protected]": {
"ledger": {
"addedDate": "2026-05-30T00:00:00.000Z",
"reason": "CVE-2021-12345 fix",
"source": "manual"
}
}
}
}
}🐑 Found potentially unused patch files:
- patches/old-package+1.0.0.patch// debug-override.js
import { resolveJSON, update } from "pastoralist";
const path = "./package.json";
const config = resolveJSON(path);
if (config) {
update({ config, debug: true, path });
}
// Check the debug output for dependency paths// analyze-appendix.js
import fs from "fs";
const pkg = JSON.parse(fs.readFileSync("./package.json", "utf-8"));
const appendix = pkg.pastoralist?.appendix || {};
console.log("Override Report:");
Object.entries(appendix).forEach(([override, info]) => {
console.log(`\n${override}:`);
console.log(" Dependents:", Object.keys(info.dependents || {}));
console.log(" Patches:", info.patches || "none");
});