{"record":{"id":"9366211c91bd158b","repo":"abhigyanpatwari/GitNexus","slug":"cannot-resume-embedding-checkpoint-no-embedding-i","errorCode":null,"errorMessage":"Cannot resume embedding checkpoint: no embedding identity was resolved.","messagePattern":"Cannot resume embedding checkpoint: no embedding identity was resolved\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/run-analyze.ts","lineNumber":1315,"sourceCode":"  let resumedEmbeddingCheckpoint: EmbeddingCheckpoint | undefined;\n  if (existingMeta?.embeddingCheckpoint) {\n    const checkpoint = existingMeta.embeddingCheckpoint;\n    // The verdict itself lives in embedding-checkpoint.ts, shared with\n    // `POST /api/embed` — two readers of one marker must not be able to\n    // disagree about what it means.\n    //\n    // The identity stays LAZY, as it has to: the flag and retry-budget verdicts\n    // short-circuit before one is needed, and resolving it means importing an\n    // embeddings module (#2370 — none loads unless a run actually needs one).\n    // `decideEmbeddingResume` asks for it by aborting on `undefined`, which is\n    // the only abort it can reach without one.\n    let decision = decideEmbeddingResume(checkpoint, undefined, options);\n    if (decision.action === 'abort') {\n      const { resolveEmbeddingIdentity } = await import('./embeddings/embedding-identity.js');\n      embeddingIdentityForRun = resolveEmbeddingIdentity();\n      decision = decideEmbeddingResume(checkpoint, embeddingIdentityForRun, options);\n    }\n    if (decision.action === 'abort') throw new Error(decision.error);\n    log(decision.log);\n    if (options.dropEmbeddings) {\n      // --drop-embeddings has always implied a rebuild here; the decision only\n      // covers the marker.\n      options = { ...options, force: true };\n    }\n    if (decision.action === 'resume') {\n      resumeEmbeddingCheckpoint = true;\n      pendingEmbeddingNodeIds = new Set(decision.pendingNodeIds);\n      resumedEmbeddingCheckpoint = decision.resumedFrom;\n    }\n  }\n\n  // ── Crash recovery: dirty flag forces full rebuild ────────────────\n  // If the previous incremental run set incrementalInProgress and didn't\n  // clear it, the on-disk index may be in a half-state. Cheapest path\n  // back to a known-good index is to wipe + rebuild from scratch.\n  if (existingMeta?.incrementalInProgress) {","sourceCodeStart":1297,"sourceCodeEnd":1333,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/run-analyze.ts#L1297-L1333","documentation":"Thrown when `decideEmbeddingResume` returns `{ action: 'abort', error: 'Cannot resume embedding checkpoint: no embedding identity was resolved.' }` and the re-invocation after resolving the identity still aborts. The embedding identity (model, dimensions, provider) is resolved lazily because importing the embeddings module is expensive. When `resolveEmbeddingIdentity()` returns undefined — no embedding configuration is available — the function cannot determine whether the checkpoint's pending nodes belong to the same vector space, so it fails closed to prevent vector-space mixing.","triggerScenarios":"An `embeddingCheckpoint` exists in `meta.json` whose kind is `'interrupted'` or `'partial'` (not `'unverified-count'`, which skips the identity gate), and `resolveEmbeddingIdentity()` returns undefined because no embedding endpoint/model is configured in the current environment.","commonSituations":"A CI job or hook ran `gitnexus analyze --embeddings` with `GITNEXUS_EMBEDDING_URL` set, crashed, and left an 'interrupted' checkpoint; a subsequent run in an environment without the embedding env vars hits the identity-resolution failure.","solutions":["Set the embedding environment variables (`GITNEXUS_EMBEDDING_URL`, `GITNEXUS_EMBEDDING_MODEL`) to match the configuration used when the checkpoint was created, then re-run `gitnexus analyze`.","If you no longer need embeddings, run `gitnexus analyze --drop-embeddings` to discard the checkpoint and index without embeddings.","Run `gitnexus analyze --force` to rebuild from scratch (this discards the checkpoint via the force path)."],"exampleFix":"// before\ngitnexus analyze\n// error: Cannot resume embedding checkpoint: no embedding identity was resolved.\n// after\nexport GITNEXUS_EMBEDDING_URL=https://api.openai.com/v1\ngitnexus analyze\n// or: gitnexus analyze --drop-embeddings","handlingStrategy":"validation","validationCode":"// Before analyze, check if a checkpoint exists and whether an embedding identity can be resolved:\nimport { loadMeta } from './storage/repo-manager.js';\nconst meta = await loadMeta(metaDir);\nif (meta?.embeddingCheckpoint) {\n  // Ensure embedding env vars are set if the checkpoint is 'interrupted' or 'partial'\n  if (!process.env.GITNEXUS_EMBEDDING_URL) {\n    console.error('An embedding checkpoint exists but GITNEXUS_EMBEDDING_URL is not set.');\n    console.error('Set the matching config or run `gitnexus analyze --drop-embeddings`.');\n    process.exit(1);\n  }\n}","typeGuard":"import { checkpointKind } from './embedding-checkpoint.js';\nconst needsEmbeddingIdentity = (checkpoint: EmbeddingCheckpoint): boolean => {\n  const kind = checkpointKind(checkpoint);\n  return kind === 'interrupted' || kind === 'partial';\n};","tryCatchPattern":"try {\n  await runAnalyze(options);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('no embedding identity was resolved')) {\n    console.error('Set GITNEXUS_EMBEDDING_URL/MODEL to match the checkpoint, or run --drop-embeddings.');\n  }\n  throw err;\n}","preventionTips":["Always set `GITNEXUS_EMBEDDING_URL` and `GITNEXUS_EMBEDDING_MODEL` consistently across environments that share an index.","Use `--drop-embeddings` when you intentionally run without embeddings to avoid leaving unresolvable checkpoints."],"tags":["embeddings","checkpoint","resume","configuration"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}