Yeachan-Heo/oh-my-codex · error · Error

failed to persist HUD authority rate-limit state

Error message

failed to persist HUD authority rate-limit state

What it means

While holding the authority lock, the HUD authority tick re-read the state file and it failed validation; the attempted invalid-state diagnostic write failed as well, so after releasing the lock the tick throws this error. It indicates both a corrupt state file and an inability to persist diagnostics under the lock.

Source

Thrown at src/hud/authority.ts:429

      next_allowed_at: diagnosticState?.next_allowed_at,
      skip_count: (diagnosticState?.skip_count ?? 0) + 1,
      last_status: 'locked',
      last_reason: 'spawn_lock_active',
      last_error: diagnosticState?.last_error,
    });
    await writeAuthorityState(authorityOwnerPath, lockedState);
    return;
  }

  await deps.onLockAcquired?.();

  let lockedState: HudAuthorityState | null;
  try {
    lockedState = await readAuthorityState(authorityStatePath);
  } catch (error) {
    const diagnosticWritten = await writeInvalidStateDiagnostic(authorityStatePath, authorityOwnerPath, cwd, nowMs, minIntervalMs, jitterMs, error);
    await releaseAuthorityLock(lock);
    if (!diagnosticWritten) throw new Error('failed to persist HUD authority rate-limit state');
    return;
  }
  const lockedNextAllowedMs = parseIsoMs(lockedState?.next_allowed_at);
  if (lockedState && lockedNextAllowedMs !== null && nowMs < lockedNextAllowedMs) {
    await writeRateLimitSkipState(
      authorityStatePath,
      authorityOwnerPath,
      cwd,
      nowMs,
      minIntervalMs,
      jitterMs,
      lockedState,
      'rate_limited_after_lock',
    );
    await releaseAuthorityLock(lock);
    return;
  }

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Repair or delete the corrupt authority state file
2. Fix write permissions on the state/diagnostic directory
3. Ensure sufficient disk space
4. Prevent concurrent runs with mismatched versions from sharing state

// before ticking: validate state and writability
const raw = JSON.parse(fs.readFileSync(authorityStatePath,'utf8'));
fs.accessSync(dirname(authorityStatePath), fs.constants.W_OK);

catch (e) { if ((e as Error).message === 'failed to persist HUD authority rate-limit state') { /* remove corrupt state, fix perms, retry tick */ } }

When it happens

Trigger: Inside runHudAuthorityTick after acquiring the lock: readAuthorityState throws, writeInvalidStateDiagnostic returns false (unwritable path, EACCES, ENOSPC, missing directory), lock is released, and this error is thrown.

Common situations: Concurrent instances writing incompatible state schemas, permission drift on the state directory, disk full, or a crash mid-write leaving a truncated state file combined with restricted diagnostic paths.

Related errors

• failed to persist HUD authority invalid-state diagnostic
• ${label} not found: ${path}
• Missing ${field}.
• timed out waiting for tmux extended-keys lease lock: ${lockP
• Refusing malformed active_skills in ${path}.

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/d4d671919c56e9aa. Report an issue: GitHub.