DEV Community

Zane
Zane

Posted on

Resolving lint-staged + pidtree Failures During Git Pre-Commit Hooks

#javascript #git #typescript #node

Resolving lint-staged + pidtree Failures During Git Pre-Commit Hooks

Overview

Projects that rely on Husky combined with lint-staged may occasionally encounter pre-commit failures, particularly when running ESLint, Prettier, and Stylelint on staged files. One commonly observed issue is an unexpected crash originating from the pidtree dependency, which results in aborted commits and reverted changes.

This document provides a comprehensive and professional guideline for diagnosing, mitigating, and permanently resolving issues involving:

  • eslint --fix failures
  • lint-staged rollback interruptions
  • pidtree: No matching pid found errors
  • blocked Husky pre-commit hooks

The procedures below ensure that code changes remain safe and that teams maintain stable, predictable pre-commit behavior.

1. Symptoms

During a standard commit operation:

git commit -m "feat: add dashboard module"
Enter fullscreen mode Exit fullscreen mode

The following symptoms may appear:

eslint --fix [FAILED]
Reverting to original state because of errors...
Error: No matching pid found
    at pidtree...
husky - pre-commit hook exited with code 1 (error)
Enter fullscreen mode Exit fullscreen mode

Common signs include:

  • ESLint unable to auto-fix staged files
  • lint-staged leaving the working directory in a partially reverted state
  • pidtree throwing exceptions while cleaning child processes
  • the commit operation being aborted

2. Root Causes

2.1 ESLint Rule Violations

lint-staged stops immediately when ESLint encounters errors that cannot be automatically fixed. This is the most frequent cause of commit failures.

2.2 pidtree Failures Under Node 18+

pidtree@0.5.0 has known instability under newer Node versions (including Node 18 and 20). The error:

No matching pid found
Enter fullscreen mode Exit fullscreen mode

occurs because lint-staged attempts to terminate a process that has already exited, leading to an unhandled exception.

2.3 Interrupted Rollback

lint-staged temporarily stashes local changes to run tasks in a clean state. If an error interrupts the restore phase, it may appear as if code was lost, although the data typically remains recoverable via git status, git diff, or git stash.

3. Immediate Workaround (Safe Commit Bypass)

If you have already validated your changes and need to commit urgently, you can bypass Husky for this commit only:

git add .
HUSKY=0 git commit -m "feat: add dashboard module"
Enter fullscreen mode Exit fullscreen mode

This is safe and does not disable hooks globally or affect other contributors.

4. Permanent and Recommended Fixes

4.1 Ensure ESLint Passes Locally

Run ESLint directly to identify real rule violations:

npx eslint "apps/**/*.ts" "apps/**/*.vue" --fix
Enter fullscreen mode Exit fullscreen mode

Or via your project scripts:

pnpm lint
Enter fullscreen mode Exit fullscreen mode

Once the workspace is lint-clean, commit attempts are significantly more stable.

4.2 Upgrade lint-staged (Highly Recommended)

Updating lint-staged ensures newer, stable versions of the pidtree dependency are used. This is the most effective long-term fix.

Upgrade:

pnpm up lint-staged@latest -D
Enter fullscreen mode Exit fullscreen mode

Verify:

npx lint-staged --debug
Enter fullscreen mode Exit fullscreen mode

If the debug run completes successfully, the issue is resolved.

4.3 Optimize lint-staged Configuration

Large or overly broad file-globs increase lint-staged load, making pidtree failures more likely. A refined configuration improves reliability.

package.json

"lint-staged": {
  "*.{js,ts,vue}": [
    "eslint --fix",
    "prettier --write"
  ],
  "*.scss": [
    "stylelint --fix"
  ]
}
Enter fullscreen mode Exit fullscreen mode

Avoid matching thousands of files when only a few are staged.

4.4 Optional: Disable pidtree Behavior (Temporary Mitigation)

For teams unable to upgrade dependencies immediately:

LINT_STAGED_PIDTREE=0 git commit -m "feat: add dashboard module"
Enter fullscreen mode Exit fullscreen mode

This prevents lint-staged from killing process trees and avoids pidtree from triggering errors.

(Not recommended as a long-term solution.)

5. Recovering “Lost” Code

Even when lint-staged rollback fails, changes are normally not lost. Use these commands to inspect them:

Check workspace: 

git status
git diff
Enter fullscreen mode Exit fullscreen mode

Check staged diff: 

git diff --staged
Enter fullscreen mode Exit fullscreen mode

Check if lint-staged created a stash: 

git stash list
git stash show -p stash@{0}
Enter fullscreen mode Exit fullscreen mode

Restore if needed:

git stash apply stash@{0}
Enter fullscreen mode Exit fullscreen mode

This resolves almost all cases where files appear missing.

6. Recommended Team Workflow

Before committing: 

pnpm lint
pnpm prettier
pnpm stylelint
Enter fullscreen mode Exit fullscreen mode

After verifying a clean workspace: 

git add .
git commit -m "feat: ..."
Enter fullscreen mode Exit fullscreen mode

This approach reduces friction, prevents pre-commit failures, and ensures a consistent codebase.

7. Summary

Issue Cause Solution
ESLint auto-fix failed Code rule violations Run ESLint manually and fix errors
pidtree: No matching pid found Node 18+ + outdated pidtree Upgrade lint-staged
lint-staged rollback error Interrupted restore Restore via stash or diff
Temporary need to commit Pre-commit blocking Use HUSKY=0 git commit

Upgrading lint-staged and keeping ESLint clean are the most effective and permanent solutions.

Top comments (0)