abhigyanpatwari/GitNexus · warning

[group] skipping corrupt contract row in contracts.json

Error message

[group] skipping corrupt contract row in contracts.json

What it means

Emitted while resiliently loading a group's contracts.json (loadContractRegistryResilient). A row in the top-level contracts array failed the isStoredContract shape check — string contractId/type/repo/symbolUid/symbolName, role of 'provider' or 'consumer', numeric confidence, and object meta and symbolRef (with filePath and name strings). The row is counted in skippedCorrupt and dropped while the rest of the registry loads normally.

Source

Thrown at gitnexus/src/core/group/service.ts:314

  if (!root || typeof root !== 'object' || Array.isArray(root)) {
    return { ok: false, error: 'contracts.json has an invalid root object' };
  }

  const base = root as Record<string, unknown>;
  const contractsRaw = base.contracts;
  const crossRaw = base.crossLinks;
  let skippedCorrupt = 0;

  const contracts: StoredContract[] = [];
  if (Array.isArray(contractsRaw)) {
    for (const row of contractsRaw) {
      try {
        if (isStoredContract(row)) {
          contracts.push(row);
        } else {
          skippedCorrupt++;
          logger.warn('[group] skipping corrupt contract row in contracts.json');
        }
      } catch {
        skippedCorrupt++;
        logger.warn('[group] skipping corrupt contract row in contracts.json');
      }
    }
  }

  const crossLinks: CrossLink[] = [];
  if (Array.isArray(crossRaw)) {
    for (const row of crossRaw) {
      try {
        if (isCrossLink(row)) {
          crossLinks.push(row);
        } else {
          skippedCorrupt++;
          logger.warn('[group] skipping corrupt crossLinks row in contracts.json');
        }

View on GitHub (pinned to 52924ef12c)

Solutions

1. Re-run group sync to regenerate contracts.json from current indexes
2. If corruption persists, delete the group's contracts.json and re-analyze the group
3. If a custom tool writes contracts.json, align its rows with the StoredContract shape (contractId, type, repo, role, symbolUid, symbolName, confidence, meta, symbolRef.filePath, symbolRef.name)

Example fix

// before — corrupt row in contracts.json
{ "contractId": "c1", "type": "http", "repo": "api", "role": "providr" }

// after — shape-valid row
{ "contractId": "c1", "type": "http", "repo": "api", "role": "provider",
  "symbolUid": "uid:1", "symbolName": "handler", "confidence": 0.9,
  "meta": {}, "symbolRef": { "filePath": "src/a.ts", "name": "handler" } }

// Pre-flight: validate contracts.json rows before loading the registry
import { readFileSync } from 'node:fs';
const registry = JSON.parse(readFileSync('contracts.json', 'utf8'));
const bad = (registry.contracts ?? []).filter((r: unknown) => !isStoredContract(r));
if (bad.length > 0) {
  throw new Error(`${bad.length} contract row(s) failed the StoredContract shape — regenerate via group sync`);
}

function isStoredContract(raw: unknown): raw is StoredContract {
  if (!raw || typeof raw !== 'object') return false;
  const o = raw as Record<string, unknown>;
  return (
    typeof o.contractId === 'string' &&
    typeof o.type === 'string' &&
    typeof o.repo === 'string' &&
    (o.role === 'provider' || o.role === 'consumer') &&
    typeof o.symbolUid === 'string' &&
    typeof o.symbolName === 'string' &&
    typeof o.confidence === 'number' &&
    o.meta !== undefined && typeof o.meta === 'object' && o.meta !== null &&
    o.symbolRef !== undefined && typeof o.symbolRef === 'object' && o.symbolRef !== null &&
    typeof (o.symbolRef as Record<string, unknown>).filePath === 'string' &&
    typeof (o.symbolRef as Record<string, unknown>).name === 'string'
  );
}

When it happens

Trigger: contracts.json contains a row whose fields are missing or of the wrong type: a crash/kill during group sync left a partially written file, the file was hand-edited, or an older/newer GitNexus version wrote a different StoredContract schema.

Common situations: Interrupted group_sync leaving truncated-but-parseable JSON; upgrading GitNexus across a StoredContract schema change; external tooling appending rows to contracts.json.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• [group] skipping corrupt crossLinks row in contracts.json
• [group/sync] manifest link ${link.type}:${link.contract} ref
• Bridge query prepare failed: ${errMsg}
• Invalid YAML: expected an object
• version is required in group.yaml

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