What causes "invalid source for %q tool: source %q is not a compatible type" in googleapis/mcp-toolbox?

Point the tool's source at a kind: cloudhealthcare source in tools.yaml.

invalid source for %q tool: source %q is not a compatible ty

Error message

invalid source for %q tool: source %q is not a compatible type

What it means

ValidateSource for the cloudhealthcare-fhir-patient-search tool asserts that the bound source implements the tool's compatibleSource interface (the Cloud Healthcare source methods this tool depends on). Any source whose concrete type fails that assertion triggers this error. It is a startup/config-time wiring check, guaranteeing the tool only runs against a compatible Cloud Healthcare source.

Source

Thrown at internal/tools/cloudhealthcare/cloudhealthcarefhirpatientsearch/cloudhealthcarefhirpatientsearch.go:123

// validate interface
var _ tools.Tool = Tool{}

type Tool struct {
	tools.BaseTool[Config]
}

func (t Tool) GetSourceName() string {
	return t.Cfg.Source
}

func (t Tool) ToConfig() tools.ToolConfig {
	return t.Cfg
}

func (t Tool) ValidateSource(source sources.Source) error {
	_, ok := source.(compatibleSource)
	if !ok {
		return fmt.Errorf("invalid source for %q tool: source %q is not a compatible type", t.Cfg.Type, t.Cfg.Source)
	}
	return nil
}

func (t Tool) Invoke(ctx context.Context, s sources.Source, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) {
	source, ok := s.(compatibleSource)
	if !ok {
		return nil, util.NewClientServerError("source used is not compatible with the tool", http.StatusInternalServerError, nil)
	}
	storeID, err := common.ValidateAndFetchStoreID(params, source.AllowedFHIRStores())
	if err != nil {
		return nil, util.NewAgentError("failed to validate store ID", err)
	}

	var tokenStr string
	if source.UseClientAuthorization() {
		tokenStr, err = accessToken.ParseBearerToken()
		if err != nil {

View on GitHub (pinned to 8cc6e09de2)

Solutions

Point the tool's source at a kind: cloudhealthcare source in tools.yaml.
Correct the source name referenced by the tool (check for typos).
Implement all compatibleSource methods on any custom/mock source.
Rebuild so the registered source is the concrete cloudhealthcare Source type.

Example fix

# before
tools:
  fhir-patient-search:
    kind: cloudhealthcare-fhir-patient-search
    source: my-mssql   # not a cloudhealthcare source

# after
tools:
  fhir-patient-search:
    kind: cloudhealthcare-fhir-patient-search
    source: my-healthcare # kind: cloudhealthcare

Defensive patterns

Strategy: type-guard

Validate before calling

func checkBinding(toolKind, sourceKind string) error {
	if strings.HasPrefix(toolKind, "cloudhealthcare-") && sourceKind != "cloudhealthcare" {
		return fmt.Errorf("tool %s requires a cloudhealthcare source, got %s", toolKind, sourceKind)
	}
	return nil
}

Type guard

if _, ok := src.(compatibleSource); !ok { /* handle before ValidateSource */ }

Try / catch

if err := tool.ValidateSource(src); err != nil {
	log.Fatalf("invalid tool/source binding (non-recoverable): %v", err)
}

Prevention

Match tool kind prefix to source kind when editing tools.yaml.
Grep your config for source names and confirm each declared kind.
Keep mocks interface-complete with compile-time assertions.
Re-validate bindings after upgrading the toolbox version.

When it happens

Trigger: ValidateSource(source) is called during tool/source binding with a source that is not the cloudhealthcare Source (e.g. postgres, http, storage) or a stub missing compatibleSource methods.

Common situations: tools.yaml binds the tool to a source declared with the wrong kind; a typo in the source name selects a different source; a custom test double doesn't implement the full interface; a refactor changed the source package so it no longer satisfies the interface.

Related errors

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