abhigyanpatwari/GitNexus · warning · Error

[understand-quickly] expected id of the form "owner/repo"…

Error message

[understand-quickly] expected id of the form "owner/repo", got "${id}". The registry uses this string to look up your entry in registry.json — it must match the GitHub owner/repo of the source code, not a local path.

What it means

While acquiring the LadybugDB init lock, GitNexus found a lock whose owning PID is no longer alive, or whose timestamp is older than INIT_LOCK_STALE_MS (30 seconds). It unlinks the stale lock and returns true so the caller retries acquisition. This is self-healing crash recovery after an unclean shutdown, not an active failure.

Solutions

  1. No action needed after a known crash — the lock is reclaimed automatically and init proceeds
  2. If it recurs without crashes, find what is holding locks >30s (hung process, antivirus file lock) in the storage directory
  3. Avoid hard-killing analyzer processes (SIGKILL / taskkill /F); prefer SIGINT so cleanup handlers run
  4. Ensure only one analyzer runs against a storage directory at a time
Defensive patterns

Strategy: retry

Validate before calling

import fs from 'node:fs/promises';
// before acquiring: preemptively clear a lock whose owner is dead or older than 30s
const parsed = JSON.parse(await fs.readFile(lockPath, 'utf8').catch(() => 'null'));
const stale =
  parsed === null ||
  (typeof parsed.pid === 'number' && !isProcessAlive(parsed.pid)) ||
  (typeof parsed.ts === 'number' && Date.now() - parsed.ts > 30_000);
if (parsed !== null && stale) await fs.unlink(lockPath).catch(() => {});

Type guard

const isStaleLock = (parsed: unknown, staleMs = 30_000): boolean => {
  if (typeof parsed !== 'object' || parsed === null) return true;
  const { pid, ts } = parsed as { pid?: unknown; ts?: unknown };
  if (typeof ts === 'number' && Date.now() - ts < staleMs && typeof pid === 'number' && isProcessAlive(pid)) return false;
  return true;
};

Prevention

When it happens

Trigger: A previous analyzer process crashed (or was SIGKILLed) leaving the contentless init lock file behind; or a live-but-hung process held the lock past 30s, so it is treated as stale and reclaimed via fs.unlink(lockPath).

Common situations: CI jobs killed mid-analyze; a developer Ctrl-C'ing during init on Windows where cleanup handlers missed the lock; two analyzers pointed at the same storage dir where one died. The warn after a known crash is benign — the next acquire succeeds.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@aac7515d2a (2026-08-20). Data as JSON: /api/errors/f48fb4def00f31ba. Report an issue: GitHub.

Appendix: source

Thrown at gitnexus-shared/src/integrations/understand-quickly.ts:51

export const UNDERSTAND_QUICKLY_TOKEN_ENV = 'UNDERSTAND_QUICKLY_TOKEN';

export interface UqDispatchPayload {
  event_type: typeof UNDERSTAND_QUICKLY_EVENT_TYPE;
  client_payload: {
    /** `<owner>/<repo>` shape — must match the registered entry. */
    id: string;
  };
}

/**
 * Build the JSON body for the `repository_dispatch` ping. Pure — no
 * env reads, no network. Validates that `id` looks like `owner/repo`
 * (one slash, no whitespace, both halves non-empty) so a misconfigured
 * caller fails loudly before the round-trip.
 */
export function buildUqDispatchPayload(id: string): UqDispatchPayload {
  if (!isValidOwnerRepo(id)) {
    throw new Error(
      `[understand-quickly] expected id of the form "owner/repo", got "${id}". ` +
        `The registry uses this string to look up your entry in registry.json — ` +
        `it must match the GitHub owner/repo of the source code, not a local path.`,
    );
  }
  return {
    event_type: UNDERSTAND_QUICKLY_EVENT_TYPE,
    client_payload: { id },
  };
}

/**
 * `owner/repo` validation. Conservative on purpose: GitHub's actual
 * naming rules are looser, but we want to catch local paths
 * (`/Users/...`), bare slugs (`my-repo`), and accidental whitespace.
 *
 * Matches GitHub's published slug rules:
 *   owner: starts with alnum, then alnum/hyphen only, must end with

View on GitHub (pinned to aac7515d2a)