ruvnet/ruflo · error

Attention mechanism '${type}' not registered

Error message

Attention mechanism '${type}' not registered

What it means

AttentionRegistry is a map of attention mechanism implementations keyed by their type string (e.g. those registered by createDefaultRegistry: multi_head, self, cross, causal, flash, flash_v2, etc.). get(type) throws this error when no mechanism was ever registered under the requested key — either because a custom empty registry was passed to AttentionExecutor, or the type string does not match any registered mechanism.

Source

Thrown at v3/@claude-flow/plugins/src/integrations/ruvector/attention.ts:140

    ];
    categories.forEach(cat => this.categoryIndex.set(cat, new Set()));
  }

  /**
   * Register an attention mechanism implementation.
   */
  register(impl: IAttentionMechanism): void {
    this.mechanisms.set(impl.type, impl);
    this.categoryIndex.get(impl.category)?.add(impl.type);
  }

  /**
   * Get an attention mechanism by type.
   */
  get(type: AttentionMechanism): IAttentionMechanism {
    const mechanism = this.mechanisms.get(type);
    if (!mechanism) {
      throw new Error(`Attention mechanism '${type}' not registered`);
    }
    return mechanism;
  }

  /**
   * Check if a mechanism is registered.
   */
  has(type: AttentionMechanism): boolean {
    return this.mechanisms.has(type);
  }

  /**
   * List all registered attention mechanisms.
   */
  listAvailable(): AttentionMechanism[] {
    return Array.from(this.mechanisms.keys());
  }

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Check availability first with registry.has(type) (or list registered types) and fail with a helpful message
2. If you built the registry yourself, register the mechanism: registry.register(new SelfAttention()) before calling get
3. Pass createDefaultRegistry() to AttentionExecutor so all built-in mechanisms exist
4. Verify the exact type string against the AttentionMechanism type union your version exports

Example fix

// before
const impl = registry.get('multihead' as AttentionMechanism); // throws

// after
if (!registry.has('multi_head')) {
  registry.register(new MultiHeadAttention());
}
const impl = registry.get('multi_head');

const mechanism = inputFromConfig as AttentionMechanism;
if (!registry.has(mechanism)) {
  throw new Error(`Unknown attention mechanism '${mechanism}'. Registered: ${Array.from(/* keys via has() probes or */ knownMechanisms).join(', ')}`);
}

function isAttentionMechanism(registry: AttentionRegistry, type: string): type is AttentionMechanism {
  return registry.has(type as AttentionMechanism);
}

try {
  const impl = registry.get(mechanism);
} catch (err) {
  if (err instanceof Error && err.message.includes('not registered')) {
    // fall back to a safe default mechanism or register the requested one
    registry.register(new SelfAttention());
  } else throw err;
}

When it happens

Trigger: Calling registry.get(type) or executor.execute(type, input) with a misspelled or unregistered mechanism string; constructing AttentionExecutor with 'new AttentionRegistry()' (empty) instead of createDefaultRegistry(); calling unregister() earlier and then get(); passing a mechanism valid in a newer version on an older build.

Common situations: Typos like 'multihead' vs 'multi_head' or 'flash-attention' vs 'flash'; using a custom registry but forgetting to register needed mechanisms; version drift where a mechanism was renamed; JSON/env-driven config supplying an arbitrary mechanism name.

Related errors

• Flash attention not initialized
• MoE attention not initialized
• Hyperbolic attention not initialized
• Hard negative miner not initialized
• Pattern not found: ${patternId}

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