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

Bind the tool to a source of kind bigquery.

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 bigquery-execute-sql tool asserts that the supplied sources.Source implements compatibleSource (the BigQuery source interface). If the type assertion fails, the tool cannot safely operate on the source, so it returns this error instead of proceeding. It is a startup-time sanity check that the tool is bound to a BigQuery source.

Source

Thrown at internal/tools/bigquery/bigqueryexecutesql/bigqueryexecutesql.go:115

// 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)
	}
	paramsMap := params.AsMap()
	sql, ok := paramsMap["sql"].(string)
	if !ok {
		return nil, util.NewAgentError(fmt.Sprintf("unable to cast sql parameter %s", paramsMap["sql"]), nil)
	}
	dryRun, ok := paramsMap["dry_run"].(bool)
	if !ok {
		return nil, util.NewAgentError(fmt.Sprintf("unable to cast dry_run parameter %s", paramsMap["dry_run"]), nil)
	}

View on GitHub (pinned to 8cc6e09de2)

Solutions

Bind the tool to a source of kind bigquery.
If wrapping BigQuery, make the wrapper implement the compatibleSource interface.
Confirm the source name referenced in the tool config exists and is the BigQuery source.
Re-run server startup so the corrected config is picked up.

Example fix

// before
tools:
  exec-sql:
    kind: bigquery-execute-sql
    source: my-alloydb-source
// after
tools:
  exec-sql:
    kind: bigquery-execute-sql
    source: my-bigquery-source

Defensive patterns

Strategy: type-guard

Validate before calling

func sourceIsBigQuery(s sources.Source) bool { _, ok := s.(interface{ BigQueryWriteMode() string }); return ok }
// call tool.ValidateSource(src) during wiring and fail fast on error

Type guard

func asCompatible(s sources.Source) (compatibleSource, bool) { c, ok := s.(compatibleSource); return c, ok }

Try / catch

if err := tool.ValidateSource(src); err != nil {
    return fmt.Errorf("binding check failed: %w", err)
}

Prevention

Call ValidateSource at wiring time so mismatches surface before serving.
Keep a one-to-one mapping between tool kind and source kind in configs.
Avoid wrapping sources without forwarding the required interface methods.
Test tool/source bindings with the real source implementations.

When it happens

Trigger: Calling ValidateSource with a source that is not a BigQuery compatibleSource — typically because the tool was registered under a source name that maps to a different database kind.

Common situations: Misconfigured tools.yaml binding the execute-sql tool to a Postgres/CloudSQL source; refactoring that replaced the BigQuery source with a wrapper type; mixing sources across toolbox instances in tests.

Related errors

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