{"record":{"id":"9cc0561925c290c4","repo":"ruvnet/ruflo","slug":"sona-not-initialized-call-initializetraining-with","errorCode":null,"errorMessage":"SONA not initialized. Call initializeTraining with useSona: true","messagePattern":"SONA not initialized\\. Call initializeTraining with useSona: true","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/services/ruvector-training.ts","lineNumber":716,"sourceCode":"// ============================================\n\n/**\n * Check if SONA is available\n */\nexport function isSonaAvailable(): boolean {\n  return sonaAvailable && sonaEngine !== null;\n}\n\n/**\n * Force-learn a pattern with SONA (1.6μs, 624k ops/s)\n * This is a one-shot learning mechanism for immediate pattern storage\n */\nexport function sonaForceLearn(\n  embedding: Float32Array,\n  reward: number\n): void {\n  if (!sonaEngine) {\n    throw new Error('SONA not initialized. Call initializeTraining with useSona: true');\n  }\n\n  sonaEngine.forceLearn(embedding, reward);\n  totalSonaLearns++;\n}\n\n/**\n * Search for similar patterns with SONA (16.7μs, 60k searches/s)\n * Returns the k most similar patterns from the pattern bank\n */\nexport function sonaFindPatterns(\n  embedding: Float32Array,\n  k: number = 5\n): unknown[] {\n  if (!sonaEngine) {\n    throw new Error('SONA not initialized. Call initializeTraining with useSona: true');\n  }\n","sourceCodeStart":698,"sourceCodeEnd":734,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/cli/src/services/ruvector-training.ts#L698-L734","documentation":"Thrown by sonaForceLearn() (and its sibling sonaFindPatterns/sonaTick) when the SONA engine is null. initializeTraining() attempts SONA by default (config.useSona !== false), but on import failure of the optional @ruvector/sona package it silently sets sonaAvailable=false and leaves sonaEngine null — only warning when you explicitly passed useSona: true. So despite the message's advice, the usual cause is not a missing flag but a missing/unresolvable @ruvector/sona install (or cleanup() having flushed and nulled the engine).","triggerScenarios":"Calling sonaForceLearn after an init where the '@ruvector/sona' dynamic import threw (not installed, pruned optionalDependency, unresolvable specifier in the bundler); initializing with { useSona: false } and still calling SONA functions; calling after cleanup() (which flushes and nulls sonaEngine).","commonSituations":"Bundlers (esbuild/webpack) that can't resolve the optional CJS/ESM interop target so importWithInterop fails at runtime; slim container images; version skew where @ruvector/sona's SonaEngine export moved; tests that cleanup() between suites but keep calling one-shot learn.","solutions":["Check readiness with the exported isSonaAvailable() before any SONA call — it reflects whether the engine actually constructed.","If false, verify @ruvector/sona is present and resolvable: npm ls @ruvector/sona; reinstall without --omit=optional; for bundlers, mark it external or ensure it's in node_modules at runtime.","Call initializeTraining() (SONA is attempted by default — no flag needed once the package resolves); pass { useSona: true } so import failures at least log a warning instead of failing silently.","After cleanup(), re-run initializeTraining() before further one-shot learning."],"exampleFix":"// before\nawait initializeTraining(); // @ruvector/sona failed to import, silently skipped\nsonaForceLearn(embedding, reward); // throws 'SONA not initialized…'\n\n// after\nconst init = await initializeTraining({ useSona: true }); // logs a warning if import fails\nif (!isSonaAvailable()) {\n  throw new Error(`SONA unavailable in this install — features: ${init.features.join(', ')}`);\n}\nsonaForceLearn(embedding, reward);","handlingStrategy":"validation","validationCode":"import { initializeTraining, isSonaAvailable, sonaForceLearn } from './services/ruvector-training.js';\n\nconst init = await initializeTraining({ useSona: true }); // explicit flag ⇒ import failures at least log a warning\nif (!isSonaAvailable()) {\n  throw new Error(`SONA unavailable — install @ruvector/sona. Features: ${init.features.join(', ')}`);\n}\nsonaForceLearn(embedding, reward);","typeGuard":"import { isSonaAvailable } from './services/ruvector-training.js';\n\n// built-in readiness predicate (not a type narrow, but the module's official check):\nfunction assertSonaReady(): void {\n  if (!isSonaAvailable()) {\n    throw new Error('SONA engine absent — initializeTraining could not import @ruvector/sona');\n  }\n}","tryCatchPattern":"try {\n  sonaForceLearn(embedding, reward);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('SONA not initialized')) {\n    if (!isSonaAvailable()) {\n      // engine genuinely absent: skip one-shot learning, don't crash the caller\n      return;\n    }\n    await initializeTraining(); // was torn down by cleanup(): re-init and retry\n    sonaForceLearn(embedding, reward);\n    return;\n  }\n  throw e;\n}","preventionTips":["Call isSonaAvailable() before every SONA function — it reflects the real engine state, flags don't.","Pass { useSona: true } so a failed @ruvector/sona import logs a warning instead of silently disabling SONA.","Mark @ruvector/sona external in bundlers or ensure it ships in node_modules; dynamic optional imports fail late at runtime.","Treat one-shot learning as optional acceleration: skip gracefully when unavailable instead of throwing."],"tags":["initialization","ruvector","sona","optional-dependency","one-shot-learning"],"backgroundTag":"component-not-initialized","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}