vxcontrol/pentagi · error

barrier (done) handler is required

Error message

barrier (done) handler is required

What it means

GetPrimaryExecutor requires the Barrier handler to be non-nil; it backs the 'done' barrier tool that lets the primary agent signal task completion. Construction fails fast with this error when cfg.Barrier is nil.

Source

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

		userID:      fte.userID,
		flowID:      fte.flowID,
		mlp:         fte.mlp,
		tclp:        fte.tclp,
		vslp:        fte.vslp,
		db:          fte.db,
		store:       fte.store,
		definitions: definitions,
		handlers:    handlers,
		barriers:    map[string]struct{}{},
		summarizer:  cfg.Summarizer,
	}

	return ce, nil
}

func (fte *flowToolsExecutor) GetPrimaryExecutor(cfg PrimaryExecutorConfig) (ContextToolsExecutor, error) {
	if cfg.Barrier == nil {
		return nil, fmt.Errorf("barrier (done) handler is required")
	}

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

	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")
	}

View on GitHub (pinned to ea665308ba)

Solutions

1. Assign a non-nil Barrier handler in PrimaryExecutorConfig.
2. Ensure the barrier handler construction (done handler) ran before calling GetPrimaryExecutor.
3. Validate the config struct fields before the call.

Example fix

// before
executor, err := fte.GetPrimaryExecutor(PrimaryExecutorConfig{
  Adviser: adviser,
}) // Barrier nil
// after
executor, err := fte.GetPrimaryExecutor(PrimaryExecutorConfig{
  Barrier: barrier,
  Adviser: adviser,
})

if cfg.Barrier == nil {
    return errors.New("barrier (done) handler missing from PrimaryExecutorConfig")
}

func hasBarrier(cfg tools.PrimaryExecutorConfig) bool {
    return cfg.Barrier != nil
}

executor, err := fte.GetPrimaryExecutor(cfg)
if err != nil {
    if strings.Contains(err.Error(), "barrier (done) handler is required") {
        return fmt.Errorf("wiring bug: done handler not built: %w", err)
    }
    return err
}

When it happens

Trigger: Calling GetPrimaryExecutor with cfg.Barrier == nil — the done/barrier handler was omitted from PrimaryExecutorConfig.

Common situations: Building the primary executor config without the barrier handler; confusing PrimaryExecutorConfig with CustomExecutorConfig (which uses barrier names instead of handlers); refactoring dropped the field.

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/ad06e1ddd3ed3649. Report an issue: GitHub.