ruvnet/ruflo · error

Tool ${this.name} requires a handler

Error message

Tool ${this.name} requires a handler

What it means

MCP tool builder's build() was called before withHandler() supplied the execution handler. An MCPToolDefinition is incomplete without a handler — the tool would be advertised to clients but could not execute — so the builder refuses to emit the definition. The tool at fault is identified by this.name.

Source

Thrown at v3/@claude-flow/plugins/src/sdk/index.ts:375

    this.properties[name] = {
      type: 'array',
      description,
      items: itemsSchema,
    };
    if (options?.required) {
      this.required.push(name);
    }
    return this;
  }

  withHandler(handler: MCPToolDefinition['handler']): this {
    this.handler = handler;
    return this;
  }

  build(): MCPToolDefinition {
    if (!this.handler) {
      throw new Error(`Tool ${this.name} requires a handler`);
    }

    return {
      name: this.name,
      description: this.description,
      inputSchema: {
        type: 'object',
        properties: this.properties,
        required: this.required.length > 0 ? this.required : undefined,
      },
      handler: this.handler,
    };
  }
}

// ============================================================================
// Hook Builder
// ============================================================================

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Attach a handler with .handler(async (args) => ...) before registering the tool.
2. Validate the tool definition at build time to catch missing handlers early.

When it happens

Trigger: A tool built with the plugin SDK is executed or registered without a handler function.

Common situations: Tool builder chain missing .handler(fn) before registration.

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