googleapis/mcp-toolbox · error

%w: %q

Error message

%w: %q

What it means

DecodeConfig looks up a registered tool factory by resource type (the YAML tool kind, e.g. "trino-execute-sql"). If no factory is registered for that type string, the lookup fails and this error wrapping ErrUnknownToolType is returned. It means the tool `kind`/`type` in the tools configuration is not recognized by the binary.

Source

Thrown at internal/tools/tools.go:59

// produce the specific ToolConfig type. It returns true if the registration was
// successful, and false if a tool with the same type was already registered.
func Register(resourceType string, factory ToolConfigFactory) bool {
	if _, exists := toolRegistry[resourceType]; exists {
		// Tool with this type already exists, do not overwrite.
		return false
	}
	toolRegistry[resourceType] = factory
	return true
}

var ErrUnknownToolType = fmt.Errorf("unknown tool type")

// DecodeConfig looks up the registered factory for the given type and uses it
// to decode the tool configuration.
func DecodeConfig(ctx context.Context, resourceType string, name string, decoder *yaml.Decoder) (ToolConfig, error) {
	factory, found := toolRegistry[resourceType]
	if !found {
		return nil, fmt.Errorf("%w: %q", ErrUnknownToolType, resourceType)
	}
	toolConfig, err := factory(ctx, name, decoder)
	if err != nil {
		return nil, fmt.Errorf("unable to parse tool %q as type %q: %w", name, resourceType, err)
	}
	return toolConfig, nil
}

type ToolConfig interface {
	ToolConfigType() string
	Initialize(context.Context) (Tool, error)
}

// https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations
type ToolAnnotations struct {
	DestructiveHint *bool `json:"destructiveHint,omitempty" yaml:"destructiveHint,omitempty"`
	IdempotentHint  *bool `json:"idempotentHint,omitempty" yaml:"idempotentHint,omitempty"`
	OpenWorldHint   *bool `json:"openWorldHint,omitempty" yaml:"openWorldHint,omitempty"`

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Check the `kind:` field in the tool's YAML block against the documented tool type names and fix the typo/casing
2. Upgrade the toolbox binary to a version that supports the tool type
3. If using a custom build, import the package containing the tool so its init() registration runs
4. Verify with the error's quoted value which type string is actually being looked up

Example fix

// before (tools.yaml)
kind: trino-executesql
// after
kind: trino-execute-sql

knownTypes := []string{"trino-execute-sql", "trino-sql"} // union of supported kinds for your binary
if !slices.Contains(knownTypes, cfg.Kind) {
    return fmt.Errorf("unsupported tool kind %q; supported: %v", cfg.Kind, knownTypes)
}

var tc tools.ToolConfig
cfg, err := tools.DecodeConfig(ctx, resourceType, name, dec)
if err != nil {
    if errors.Is(err, tools.ErrUnknownToolType) {
        // reject config early with a clear message listing valid kinds
    }
    return err
}
_ = tc

When it happens

Trigger: Calling tools.DecodeConfig (via UnmarshalYAMLToolConfig while parsing the tools YAML) with a resourceType string that has no entry in toolRegistry — typically a misspelled or unsupported `kind:` value in the YAML config.

Common situations: Typo in the tool kind in tools.yaml (e.g. "trino-execut-sql"); using a tool type from a newer toolbox version than the binary being run; building a custom binary that omits the package whose init() registers the tool; wrong casing since the lookup is exact-match.

Related errors

• description is required for tool %q
• description is required for tool %q
• description is required for tool %q
• unknown tool type
• unable to parse tool %q as type %q: %w

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/5b0aa320404b123d. Report an issue: GitHub.