ruvnet/ruflo · error

Attention mechanism ' ' 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.

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
• Hard negative miner not initialized
• Hyperbolic attention not initialized
• MoE attention not initialized
• No query executor configured

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

Appendix: 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)