thedotmack/claude-mem · warning

Failed to parse PID file

Error message

Failed to parse PID file

What it means

readPidFile reads the worker's PID file and JSON.parse's it to recover the recorded pid for liveness checks and guarded removal. This warning (Error branch) fires when the file exists but its content is not valid JSON — corrupted, empty, or partially written. The function returns null, which callers treat as 'no live worker recorded', typically leading to stale-file cleanup or a fresh start.

Source

Thrown at src/services/infrastructure/ProcessManager.ts:146

  type PidInfo
} from '../../supervisor/process-registry.js';
export { captureProcessStartToken, verifyPidFileOwnership, type PidInfo };

export function writePidFile(info: PidInfo): void {
  mkdirSync(DATA_DIR, { recursive: true });
  const resolvedToken = info.startToken ?? captureProcessStartToken(info.pid);
  const payload: PidInfo = resolvedToken ? { ...info, startToken: resolvedToken } : info;
  writeFileSync(PID_FILE, JSON.stringify(payload, null, 2));
}

export function readPidFile(): PidInfo | null {
  if (!existsSync(PID_FILE)) return null;

  try {
    return JSON.parse(readFileSync(PID_FILE, 'utf-8'));
  } catch (error: unknown) {
    if (error instanceof Error) {
      logger.warn('SYSTEM', 'Failed to parse PID file', { path: PID_FILE }, error);
    } else {
      logger.warn('SYSTEM', 'Failed to parse PID file', { path: PID_FILE }, new Error(String(error)));
    }
    return null;
  }
}

export function removePidFile(): void {
  if (!existsSync(PID_FILE)) return;

  try {
    unlinkSync(PID_FILE);
  } catch (error: unknown) {
    if (error instanceof Error) {
      logger.warn('SYSTEM', 'Failed to remove PID file', { path: PID_FILE }, error);
    } else {
      logger.warn('SYSTEM', 'Failed to remove PID file', { path: PID_FILE }, new Error(String(error)));
    }

View on GitHub (pinned to e2d1df569a)

Solutions

  1. Confirm no live worker owns the recorded pid (ps/Task Manager), then delete the stale PID file — it is regenerable state.
  2. Inspect the file content; if it looks valid, the logged SyntaxError names the exact character offset of the break.
  3. If it recurs, look for concurrent writers (two workers sharing one PID_FILE path) and give each its own data dir.
  4. After removing the file, restart the worker so it writes a clean one.
Defensive patterns

Strategy: try-catch

Validate before calling

// cheap pre-check: treat empty files as absent before parsing
const txt = readFileSync(PID_FILE, 'utf-8');
if (txt.trim().length === 0) {
  removePidFile();
} else {
  const info = JSON.parse(txt) as PidInfo;
}

Type guard

function isPidInfo(v: unknown): v is { pid: number; startToken?: number } {
  return typeof v === 'object' && v !== null &&
    typeof (v as { pid?: unknown }).pid === 'number';
}

Try / catch

try {
  const info = readPidFile();
  if (info && isPidInfo(info) && isAlive(info.pid)) await stopWorker(info.pid);
} catch (e) {
  // a null return already means 'no registered worker' — proceed with fresh start
}

Prevention

When it happens

Trigger: PID_FILE exists and JSON.parse(readFileSync(...)) throws a SyntaxError: file truncated by a crash between writeFileSync and completion, zero-byte file, or foreign content written by another tool at the same path.

Common situations: Process killed mid-write; disk-full truncating the file; a different program overwriting the path; a leftover file from an old version using a different format.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

AI-assisted analysis of thedotmack/claude-mem@e2d1df569a (2026-08-20). Data as JSON: /api/errors/6785f80117895ca8. Report an issue: GitHub.