{"record":{"id":"7b440bcb2b5b6757","repo":"ruvnet/ruflo","slug":"resume-checkpoint-not-found-resumefrom","errorCode":null,"errorMessage":"--resume checkpoint not found: ${resumeFrom}","messagePattern":"--resume checkpoint not found: (.+?)","errorType":"exception","errorClass":"ResumeFailedError","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/services/native-training.ts","lineNumber":116,"sourceCode":"      epochs,\n      inputDim: dim,\n      outputDim: dim,\n    };\n    // 0 (or omitted) disables validation; only pass a real holdout through.\n    if (typeof validationSplit === 'number' && validationSplit > 0) {\n      pipelineConfig.validationSplit = validationSplit;\n    }\n    const pipeline = new ruvllm.TrainingPipeline(pipelineConfig);\n\n    // Resume BEFORE training. Prefer resumeFrom() (2.6.0 — epoch position +\n    // optimizer state); fall back to loadCheckpoint() (2.5.7 — weights only).\n    // Any failure with an explicit --resume is loud (ResumeFailedError),\n    // never silent fresh training.\n    let resumed = false;\n    let resumeMode: 'resumeFrom' | 'loadCheckpoint' | undefined;\n    if (resumeFrom) {\n      if (!existsSync(resumeFrom)) {\n        throw new ResumeFailedError(`--resume checkpoint not found: ${resumeFrom}`);\n      }\n      try {\n        if (typeof pipeline.resumeFrom === 'function') {\n          pipeline.resumeFrom(resumeFrom);\n          resumeMode = 'resumeFrom';\n        } else {\n          const ok = pipeline.loadCheckpoint(resumeFrom);\n          if (ok === false) throw new Error('loadCheckpoint returned false');\n          resumeMode = 'loadCheckpoint';\n        }\n        resumed = true;\n      } catch (e) {\n        if (e instanceof ResumeFailedError) throw e;\n        throw new ResumeFailedError(\n          `--resume failed to load checkpoint ${resumeFrom}: ${(e as Error).message}`,\n        );\n      }\n    }","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/services/native-training.ts#L98-L134","documentation":"Thrown as a ResumeFailedError by runNativeTraining() when the --resume option points at a path that does not exist on disk (existsSync returns false). This is the loud-failure design for explicit resume: a missing checkpoint must NOT silently fall through to fresh training, because that would hide data loss and destroy the epoch-position/optimizer-state the user expected to restore. ResumeFailedError is special-cased in the outer catch to re-throw rather than degrade to the null/WASM fallback used for other native-training failures.","triggerScenarios":"Invoking runNativeTraining({ resumeFrom: './ckpt.bin', ... }) where ./ckpt.bin was never written, was deleted, lives on a different machine, or the path is relative to the wrong working directory. Also fires when a previous training run failed before saveCheckpoint() wrote the file (checkpoint saving is best-effort and only present in ruvllm >=2.5.7).","commonSituations":"Pointing --resume at a checkpoint from a prior run that crashed before checkpointing; a path that was correct in one environment (CI) but absent in another (local); a relative path interpreted against an unexpected cwd; running on ruvllm <2.5.7 where saveCheckpoint writes nothing, so a 'checkpointPath' reported by a prior run never actually landed on disk.","solutions":["Verify the file exists at the absolute path before passing it: use fs.realpathSync or fs.existsSync and log the resolved path.","If the checkpoint was lost, drop --resume and start fresh training (the error is intentional — do not paper over it).","Ensure ruvllm >=2.5.7 so that prior runs actually persist checkpoints, and confirm the checkpointPath you resume from is the one a successful run reported."],"exampleFix":"// before\nawait runNativeTraining({ embeddings, epochs, batchSize, learningRate, dim, resumeFrom: opts.resume })\n// after — validate existence with an absolute path first\nimport { existsSync, realpathSync } from 'fs';\nimport { resolve } from 'path';\nconst ckpt = opts.resume ? realpathSync(resolve(opts.resume)) : undefined;\nif (opts.resume && !existsSync(ckpt)) {\n  throw new Error(`refusing to resume: checkpoint not found at ${ckpt}`);\n}\nawait runNativeTraining({ embeddings, epochs, batchSize, learningRate, dim, resumeFrom: ckpt })","handlingStrategy":"validation","validationCode":"import { existsSync, realpathSync } from 'fs';\nimport { resolve } from 'path';\nfunction resolveResumePath(resumeFrom?: string): string | undefined {\n  if (!resumeFrom) return undefined;\n  const abs = resolve(resumeFrom);\n  if (!existsSync(abs)) {\n    throw new Error(`--resume checkpoint not found at ${abs}; refusing to fresh-train silently`);\n  }\n  return realpathSync(abs);\n}","typeGuard":"import { existsSync } from 'fs';\nfunction isExistingCheckpoint(path: string): boolean {\n  return typeof path === 'string' && path.length > 0 && existsSync(path);\n}","tryCatchPattern":"import { ResumeFailedError } from './native-training.js';\ntry {\n  await runNativeTraining({ ...opts, resumeFrom });\n} catch (e) {\n  if (e instanceof ResumeFailedError) {\n    // explicit resume failure — do NOT retry as fresh training;\n    // either restore the checkpoint file or drop --resume intentionally\n    console.error(e.message);\n    process.exit(1);\n  }\n  // other failures degrade to null/WASM fallback by design\n}","preventionTips":["Resolve --resume to an absolute path and existsSync-check it before calling runNativeTraining.","Use ruvllm >=2.5.7 so checkpoints actually persist to disk.","Treat ResumeFailedError as a hard stop — never catch-and-fresh-train, that defeats the loud-failure design.","Verify the checkpointPath a prior successful run reported, not a guessed path."],"tags":["native-training","resume","checkpoint","filesystem","ruvllm"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}