googleapis/mcp-toolbox · error

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 cloud-sql-list-instances tool checks that the bound source implements its compatibleSource interface and returns this error when the type assertion fails. The tool cannot run against sources lacking the Cloud SQL Admin surface (project lookup, client-authorization flag, ListInstances operation). The error always indicates the tool was paired with an incompatible source kind in configuration or programmatic setup.

Source

Thrown at internal/tools/cloudsql/cloudsqllistinstances/cloudsqllistinstances.go:100

}

// Tool represents the list-instance 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
}

// Invoke executes the tool's logic.
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()

	project, ok := paramsMap["project"].(string)
	if !ok {
		return nil, util.NewAgentError("missing 'project' parameter", nil)
	}
	resp, err := source.ListInstance(ctx, project, string(accessToken))
	if err != nil {

View on GitHub (pinned to 8cc6e09de2)

Solutions

  1. Correct the tools.yaml source reference to a Cloud SQL Admin-compatible source.
  2. Implement the complete compatibleSource interface (GetDefaultProject, UseClientAuthorization, ListInstances) on custom sources.
  3. Keep tool and source package versions synchronized to avoid interface drift.
  4. Call ValidateSource explicitly in custom initialization to fail fast.
  5. Confirm the source's concrete type with fmt.Printf("%T", src).

Example fix

// before
listInstances.ValidateSource(postgresSource) // incompatible
// after
listInstances.ValidateSource(cloudsqlAdminSource) // implements compatibleSource
Defensive patterns

Strategy: type-guard

Validate before calling

if _, ok := src.(compatibleSource); !ok {
	return fmt.Errorf("source %T cannot back cloud-sql-list-instances", src)
}

Type guard

func isListInstancesSource(s sources.Source) bool {
	_, ok := s.(compatibleSource)
	return ok
}

Try / catch

if err := tool.ValidateSource(src); err != nil {
	return fmt.Errorf("cloud-sql-list-instances bound to wrong source: %w", err)
}

Prevention

When it happens

Trigger: ValidateSource(source) during startup toolset validation or immediately before Invoke, with a sources.Source that does not implement the tool's compatibleSource methods — e.g. a postgres or bigquery source referenced by cloud-sql-list-instances in tools.yaml.

Common situations: tools.yaml pointing the tool at a DB connection source instead of a Cloud SQL Admin source; custom source missing required interface methods after a version bump; test stubs not implementing the full interface.

Related errors

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