vxcontrol/pentagi · error

searcher handler is required

Error message

searcher handler is required

What it means

Constructor validation error (backend/pkg/tools/tools.go): the flow tool-set factory was invoked with a nil Searcher handler in its config. Programming/configuration error — all agent handlers must be wired before building the flow's tool executor.

Source

Thrown at backend/pkg/tools/tools.go:838

	if cfg.Coder == nil {
		return nil, fmt.Errorf("coder handler is required")
	}

	if cfg.Installer == nil {
		return nil, fmt.Errorf("installer handler is required")
	}

	if cfg.Memorist == nil {
		return nil, fmt.Errorf("memorist handler is required")
	}

	if cfg.Pentester == nil {
		return nil, fmt.Errorf("pentester handler is required")
	}

	if cfg.Searcher == nil {
		return nil, fmt.Errorf("searcher handler is required")
	}

	container, err := fte.db.GetFlowPrimaryContainer(context.Background(), fte.flowID)
	if err != nil {
		return nil, fmt.Errorf("failed to get container %d: %w", fte.flowID, err)
	}

	term := NewTerminalTool(
		fte.flowID, nil, nil,
		container.ID,
		container.LocalID.String,
		fte.cfg.TenantPrefix(),
		fte.docker,
		fte.tlp,
		time.Duration(fte.cfg.TerminalToolTimeout)*time.Second,
	)

	definitions := []llms.FunctionDefinition{

View on GitHub (pinned to ea665308ba)

Solutions

1. Assign a non-nil Searcher handler in AssistantExecutorConfig.
2. Configure at least one search engine in the environment so the searcher handler is created.
3. Validate all required handler fields before calling GetAssistantExecutor.

Example fix

// before
executor, err := fte.GetAssistantExecutor(AssistantExecutorConfig{
  Adviser: adviser, Coder: coder, Installer: installer, Memorist: memorist, Pentester: pentester,
}) // Searcher nil
// after
executor, err := fte.GetAssistantExecutor(AssistantExecutorConfig{
  Adviser: adviser, Coder: coder, Installer: installer, Memorist: memorist, Pentester: pentester, Searcher: searcher,
})

if cfg.Searcher == nil {
    return errors.New("searcher handler missing from AssistantExecutorConfig")
}

func hasSearcher(cfg tools.AssistantExecutorConfig) bool {
    return cfg.Searcher != nil
}

executor, err := fte.GetAssistantExecutor(cfg)
if err != nil {
    if strings.Contains(err.Error(), "searcher handler is required") {
        // verify at least one search engine is configured
        return err
    }
    return err
}

When it happens

Trigger: Calling GetAssistantExecutor with cfg.Searcher == nil, e.g. when no search engine is configured so the searcher handler was never built.

Common situations: Deployments with no search provider keys configured (DuckDuckGo/Google/Tavily etc.), producing a nil searcher; partial agent wiring.

Related errors

• adviser handler is required
• coder handler is required
• installer handler is required
• memorist handler is required
• pentester handler is required

AI-assisted analysis of vxcontrol/pentagi@ea665308ba (2026-09-01). Data as JSON: /api/errors/3a4a16cbb71cc1c2. Report an issue: GitHub.