googleapis/mcp-toolbox · error

failed to get catalog client: %w

Error message

failed to get catalog client: %w

What it means

Thrown by InvokeSearchCatalog in the Dataplex tool when getCatalogClient fails to build an authenticated Google Cloud Dataplex Catalog client. This wraps lower-level errors such as missing Application Default Credentials, invalid quota project configuration, or failure constructing the gRPC client. The underlying error is preserved via %w so callers can inspect it.

Source

Thrown at internal/sources/dataplex/searchcatalog/search_catalog.go:173

	typesSlice, err := parameters.ConvertAnySliceToTyped(paramsMap["types"].([]any), "string")
	if err != nil {
		return nil, fmt.Errorf("can't convert types to array of strings: %w", err)
	}
	types := typesSlice.([]string)

	query := ConstructSearchQuery(prompt, projectIds, parentIds, types, systemName)

	req := &dataplexpb.SearchEntriesRequest{
		Query:          query,
		Name:           fmt.Sprintf("projects/%s/locations/global", projectID),
		PageSize:       pageSize,
		SemanticSearch: true,
	}

	catalogClient, err := getCatalogClient(ctx, tokenStr)
	if err != nil {
		return nil, fmt.Errorf("failed to get catalog client: %w", err)
	}

	return ExecuteSearch(ctx, catalogClient, req, typeMap)
}

// Cache is an interface for a thread-safe, expiring key-value store.
type Cache interface {
	Get(key string) (any, bool)
	Set(key string, value any)
}

// DataplexClientManager manages Dataplex Catalog clients, including caching and lazy initialization.
type DataplexClientManager struct {
	UseClientOAuth       bool
	Cache                Cache
	DefaultClientCreator func(ctx context.Context) (*dataplexapi.CatalogClient, error)
	OAuthClientCreator   func(ctx context.Context, token string) (*dataplexapi.CatalogClient, error)

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Authenticate: run `gcloud auth application-default login` or set GOOGLE_APPLICATION_CREDENTIALS to a valid service account key.
2. Enable the Dataplex (Catalog) API on your Google Cloud project and grant the service account dataplex.catalogViewer (or higher) IAM role.
3. Check outbound network access to dataplex.googleapis.com and inspect the wrapped cause (%w) for the root error.
4. Verify the client's auth token/scopes are being passed correctly in the request context.

Example fix

// before: run with no credentials
./toolbox --prebuilt-configs dataplex

// after
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa-key.json
gcloud services enable dataplex.googleapis.com
./toolbox --prebuilt-configs dataplex

if os.Getenv("GOOGLE_APPLICATION_CREDENTIALS") == "" {
    if _, err := os.Stat(filepath.Join(os.Getenv("HOME"), ".config/gcloud/application_default_credentials.json")); err != nil {
        return errors.New("no GCP credentials: run `gcloud auth application-default login`")
    }
}

null

result, err := invokeSearchCatalog(ctx, ...)
if err != nil {
    var credErr *googleapi.Error
    if errors.Unwrap(err) != nil && strings.Contains(err.Error(), "credential") {
        // prompt user to authenticate
    }
    return fmt.Errorf("search catalog unavailable: %w", err)
}

When it happens

Trigger: Calling the dataplex search-catalog tool when the environment lacks valid Google Cloud credentials (ADC not set up), the token/context cannot produce an authorized client, or the CatalogClient construction fails (e.g., bad project, network unreachable to dataplex.googleapis.com).

Common situations: Running the toolbox locally without GOOGLE_APPLICATION_CREDENTIALS or gcloud auth; running in an environment without the required Dataplex API scopes; service account without the Dataplex Catalog viewer role; disabled Dataplex API on the project.

Related errors

• failed to initialize dataplex client: %w
• failed to get dataplex client: %w
• failed to create Dataplex client for project %q: %w
• failed to create impersonated credentials for %q for project
• failed to find default Google Cloud credentials for project

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