SONAAdapter not initialized. Call initialize() first.

Error message

SONAAdapter not initialized. Call initialize() first.

What it means

SONAAdapter uses the standard bridge pattern: methods that depend on runtime state call ensureInitialized(), which throws until initialize() has fully completed. Before that there is no pattern store, no configuration handshake, and no active trajectories.

Solutions

Use the createSONAAdapter(config) factory — it constructs and awaits initialization in one step
If initializing manually, await it before any other call and fail loudly if it rejects
Share one initialized adapter instance across the app instead of constructing per module

Example fix

// before
const adapter = new SONAAdapter(config);
await adapter.startTrajectory({ /* ... */ }); // throws: not initialized

// after
const adapter = await createSONAAdapter(config);
await adapter.startTrajectory({ /* ... */ });

Defensive patterns

Strategy: validation

Validate before calling

// Shared initialized singleton — every call site awaits the same promise
let adapterPromise: Promise<SONAAdapter> | null = null;
function getSONA(): Promise<SONAAdapter> {
  adapterPromise ??= createSONAAdapter(config);
  return adapterPromise;
}

Try / catch

try {
  await sona.startTrajectory(params);
} catch (e) {
  if (e instanceof Error && e.message.includes('SONAAdapter not initialized')) {
    const sonaReady = await createSONAAdapter(config); // then retry once with the ready instance
    return sonaReady.startTrajectory(params);
  }
  throw e;
}

Prevention

Construct via createSONAAdapter(config), never new SONAAdapter() followed by immediate use
Share one initialized instance across modules
Fail loudly on initialization rejection — the guard otherwise surfaces much later

When it happens

Trigger: Calling any adapter method (startTrajectory, recordTrajectoryStep, optimization APIs) on an instance where initialize() was never awaited, or where it failed earlier.

Common situations: Constructing with new SONAAdapter(config) and immediately calling methods; a swallowed init failure; multiple modules each constructing their own instance while only one gets initialized.

Related errors

AI-assisted analysis of ruvnet/ruflo@9c61c86f06 (2026-08-18). Data as JSON: /api/errors/29218878966d30cf. Report an issue: GitHub.

Appendix: source

Thrown at v3/@claude-flow/integration/src/sona-adapter.ts:825

    this.stats.averageConfidence = total / this.patterns.size;
  }

  private estimateMemoryUsage(): number {
    // Rough estimate: 500 bytes per pattern, 1KB per trajectory step
    const patternBytes = this.patterns.size * 500;
    const trajectoryBytes = Array.from(this.activeTrajectories.values())
      .reduce((sum, t) => sum + t.steps.length * 1024, 0);

    return patternBytes + trajectoryBytes;
  }

  private generateId(prefix: string): string {
    return `${prefix}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
  }

  private ensureInitialized(): void {
    if (!this.initialized) {
      throw new Error('SONAAdapter not initialized. Call initialize() first.');
    }
  }
}

/**
 * Create and initialize a SONA adapter
 */
export async function createSONAAdapter(
  config?: Partial<SONAConfiguration>
): Promise<SONAAdapter> {
  const adapter = new SONAAdapter(config);
  await adapter.initialize();
  return adapter;
}

View on GitHub (pinned to 9c61c86f06)