Troubleshooting & FAQ

Frequently Asked Questions

What is pastoralist?

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.

Why do I need pastoralist?

Without pastoralist, it's easy to forget why an override was added, which packages still need it, or whether it's safe to remove.

Does pastoralist work with Yarn, pnpm, and Bun?

Yes. Pastoralist reads and writes the override field your package manager uses:

• npm and Bun: overrides
• pnpm: pnpm.overrides
• Yarn: resolutions

Is pastoralist safe to use?

Pastoralist is designed to keep changes reviewable:

• Only modifies override/resolution fields and the pastoralist section of package.json
• Normalizes package.json output to two-space JSON
• Leaves changes visible in git so you can review or revert them
• Creates a temporary backup before security auto-fix writes package.json

When should overrides be used?

Use overrides for:

• Security patches before upstream updates
• Compatibility issues between packages
• Bug fixes not yet released
• Temporary workarounds

Common Issues

Overrides Not Being Removed

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 --debug

Look for output showing which packages require the override.

Package.json Formatting Changes

Problem: Pastoralist changes the formatting of my package.json.

Solution: Pastoralist rewrites package.json as two-space JSON. If you see unexpected changes:

1. Ensure you're using the latest version
2. Check if you have a .prettierrc or .editorconfig that might conflict
3. Consider running a formatter after pastoralist

Patches Not Detected

Problem: 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 detected

Performance Issues

Problem: Pastoralist takes a long time to run.

Solution: For large monorepos:

1. Run on specific packages instead of all at once
2. Use --ignore to skip unnecessary directories
3. Run packages in parallel:

# Instead of
pastoralist --depPaths "**/*package.json"

# Try
find . -name "package.json" -not -path "*/node_modules/*" | \
  xargs -P 4 -I {} npx pastoralist --path {}

Monorepo Override Conflicts

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"
  }
}

CI Failures

Problem: CI fails saying package.json was modified.

Solution: Run pastoralist locally and commit the changes:

npx pastoralist
git add package.json
git commit -m "Update override appendix"

Then add to your CI check:

- run: npx pastoralist
- run: git diff --exit-code package.json

Debug Mode

Enable debug mode for detailed information:

npx pastoralist --debug

Debug output includes:

• Package resolution paths
• Dependency tree analysis
• Override usage detection
• File operation details

Error Messages

"Cannot find package.json"

Pastoralist can't locate your package.json. Solutions:

• Run from project root
• Use --path to specify location
• Check file permissions

"Invalid package.json"

Your package.json has syntax errors. Validate with:

npx json package.json

"No overrides found"

This is normal if you don't have any overrides. Pastoralist will:

• Clean up any existing appendix
• Exit successfully

Best Practices

1. Regular Updates

Run pastoralist regularly:

{
  "scripts": {
    "postinstall": "pastoralist"
  }
}

2. Document Override Reasons

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"
        }
      }
    }
  }
}

3. Monitor Patch Files

When you see this warning:

🐑 Found potentially unused patch files:
  - patches/old-package+1.0.0.patch

Review and remove unused patches to keep your repo clean.

Getting Help

Resources

• GitHub Issues - Report bugs & ask questions

Before Filing an Issue

1. Update to the latest version
2. Run with --debug flag
3. Check existing issues
4. Provide minimal reproduction

Issue Template

When reporting issues, include:

• Pastoralist version
• Node.js version
• Package manager (npm/yarn/pnpm)
• Relevant package.json sections
• Debug output

Migration Help

From Manual Management

If you're tracking overrides manually in docs or issue trackers, Pastoralist will:

1. Document all current overrides in pastoralist.appendix
2. Track their usage going forward
3. Flag unused overrides and remove them when you run with --remove-unused

Advanced Debugging

Trace Dependency Paths

To understand why an override is needed:

// 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

// 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");
});