What causes "definitions and handlers must have the same length" in vxcontrol/pentagi?

Ensure every entry in cfg.Definitions has a unique Name and a matching key in cfg.Handlers.

definitions and handlers must have the same length

Error message

definitions and handlers must have the same length

What it means

GetCustomExecutor validates CustomExecutorConfig before building a custom tools executor: the number of tool Definitions must equal the number of entries in the Handlers map... actually it requires len(Definitions) == len(Handlers) as a quick sanity check that every definition has exactly one handler and no extras. Mismatched lengths indicate a miswired tool registration.

Source

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

		// the store owns its own connection (no shared pool configured).
		if fte.cfg.PgxPool == nil {
			fte.store.Close()
		}
		fte.store = nil
	}

	// TODO: here better to get flow containers list and purge all of them
	if err := fte.docker.RemoveContainer(ctx, fte.primaryLID, fte.primaryID); err != nil {
		containerName := PrimaryTerminalName(fte.cfg.TenantPrefix(), fte.flowID)
		return fmt.Errorf("failed to purge container '%s': %w", containerName, err)
	}

	return nil
}

func (fte *flowToolsExecutor) GetCustomExecutor(cfg CustomExecutorConfig) (ContextToolsExecutor, error) {
	if len(cfg.Definitions) != len(cfg.Handlers) {
		return nil, fmt.Errorf("definitions and handlers must have the same length")
	}

	for _, def := range cfg.Definitions {
		if _, ok := cfg.Handlers[def.Name]; !ok {
			return nil, fmt.Errorf("handler for function %s not found", def.Name)
		}
	}

	for _, builtin := range cfg.Builtin {
		if def, ok := fte.definitions[builtin]; !ok {
			return nil, fmt.Errorf("builtin function %s not found", builtin)
		} else {
			cfg.Definitions = append(cfg.Definitions, def)
			cfg.Handlers[builtin] = fte.handlers[builtin]
		}
	}

	barriers := make(map[string]struct{})

View on GitHub (pinned to ea665308ba)

Solutions

Ensure every entry in cfg.Definitions has a unique Name and a matching key in cfg.Handlers.
Build Definitions and Handlers together from a single source (e.g. a slice of {def, handler} pairs) so they cannot diverge.
Log len(cfg.Definitions) and len(cfg.Handlers) before the call to spot the mismatch.

Example fix

// before
cfg := tools.CustomExecutorConfig{
    Definitions: []tools.FunctionDefinition{defA, defB},
    Handlers:    map[string]tools.Handler{"a": hA}, // missing b
}

// after
cfg := tools.CustomExecutorConfig{
    Definitions: []tools.FunctionDefinition{defA, defB},
    Handlers:    map[string]tools.Handler{"a": hA, "b": hB},
}

Defensive patterns

Strategy: validation

Validate before calling

if len(cfg.Definitions) != len(cfg.Handlers) {
    return fmt.Errorf("definitions=%d handlers=%d: each definition needs exactly one handler",
        len(cfg.Definitions), len(cfg.Handlers))
}
if err := isUniqueNames(cfg.Definitions); err != nil {
    return err // duplicate names collapse in the Handlers map
}

Type guard

func validCustomConfig(cfg tools.CustomExecutorConfig) bool {
    if len(cfg.Definitions) != len(cfg.Handlers) {
        return false
    }
    seen := map[string]struct{}{}
    for _, d := range cfg.Definitions {
        if _, dup := seen[d.Name]; dup {
            return false
        }
        seen[d.Name] = struct{}{}
    }
    return true
}

Try / catch

executor, err := flowTools.GetCustomExecutor(cfg)
if err != nil {
    return fmt.Errorf("invalid custom tool config: %w", err)
}

Prevention

Define custom tools as a single []ToolSpec{{Def, Handler}} slice and derive Definitions/Handlers from it.
Keep function definition names unique — duplicate names collapse the handler map and break the length invariant.
Add a unit test asserting GetCustomExecutor succeeds for every shipped tool config.

When it happens

Trigger: Calling GetCustomExecutor with a CustomExecutorConfig where cfg.Definitions has N entries but cfg.Handlers map has a different count — e.g. two definitions share the same name (map collapses them) or a handler was added without a corresponding definition (and vice versa).

Common situations: Registering custom agent tools where a tool definition and its handler function drift out of sync after adding/removing a tool; duplicate FunctionDefinition names collapsing in the Handlers map; forgetting to add the handler for a newly defined function.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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