googleapis/mcp-toolbox · error

failed to create Dataplex client for project %q: %w

Error message

failed to create Dataplex client for project %q: %w

What it means

This error wraps failure from dataplexapi.NewCatalogClient() when constructing the Dataplex Data Catalog client during source initialization. Unlike ADC lookup, this typically fails on option validation (gRPC dial options, endpoint, token source inconsistencies) rather than at request time, since the client constructor itself does not call the API.

Source

Thrown at internal/sources/bigquery/bigquery.go:963

			opts = []option.ClientOption{
				option.WithUserAgent(userAgent),
				option.WithTokenSource(ts),
			}
		} else {
			// Use default credentials
			cred, err := google.FindDefaultCredentials(ctx, credScopes...)
			if err != nil {
				return nil, nil, fmt.Errorf("failed to find default Google Cloud credentials: %w", err)
			}
			opts = []option.ClientOption{
				option.WithUserAgent(userAgent),
				option.WithCredentials(cred),
			}
		}

		client, err = dataplexapi.NewCatalogClient(ctx, opts...)
		if err != nil {
			return nil, nil, fmt.Errorf("failed to create Dataplex client for project %q: %w", project, err)
		}
	}

	return client, clientCreator, nil
}

func initDataplexConnectionWithOAuthToken(
	ctx context.Context,
	project string,
	userAgent string,
	tokenString string,
) (*dataplexapi.CatalogClient, error) {
	// Construct token source
	token := &oauth2.Token{
		AccessToken: string(tokenString),
	}
	ts := oauth2.StaticTokenSource(token)

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Inspect the wrapped error (%w) — most causes mirror the credential errors above (477/478); fix the underlying credential problem first.
2. Verify the project ID is valid and the Dataplex API (dataplex.googleapis.com) is enabled: `gcloud services enable dataplex.googleapis.com`.
3. Test connectivity to the endpoint: `curl https://dataplex.googleapis.com` — configure HTTPS_PROXY for corporate networks.
4. Upgrade cloud.google.com/go/dataplex and related google.golang.org deps to consistent versions.
5. As a workaround, enable `useClientOAuth` so the client is created per-request with the caller's token instead of at startup.

Example fix

// before
client, err = dataplexapi.NewCatalogClient(ctx, opts...) // stale token source
// after
// re-mint credentials before constructing the client
cred, err := google.FindDefaultCredentials(ctx, credScopes...)
if err != nil { return nil, nil, err }
opts = append(opts, option.WithCredentials(cred))
client, err = dataplexapi.NewCatalogClient(ctx, opts...)

// pre-flight: ensure Dataplex API enabled and creds usable before constructing client
if err := exec.Command("gcloud", "services", "list", "--enabled", "--filter=dataplex.googleapis.com").Run(); err != nil {
    return fmt.Errorf("dataplex API not enabled for project %s", project)
}
if _, err := google.FindDefaultCredentials(context.Background(), CloudPlatformScope); err != nil { return err }

func isDataplexClientErr(err error) bool { return err != nil && strings.Contains(err.Error(), "failed to create Dataplex client") }

client, creator, err := initDataplexConnection(ctx, tracer, name, project, useClientOAuth, sa, scopes)
if err != nil {
    if isDataplexClientErr(err) {
        // non-retryable config/credential issue: surface actionable message
        return fmt.Errorf("dataplex init for %q: %w", project, err)
    }
    return err
}

When it happens

Trigger: initDataplexConnection with server-side (non-client-OAuth) auth where NewCatalogClient rejects the constructed options: invalid token source from a failed impersonation setup that silently degraded, invalid `project`-derived endpoint, or a grpc dial error due to transport/security option conflicts.

Common situations: Corrupt or expired credentials whose token source fails lazily at client construction; proxy/firewall interfering with gRPC channel creation; version incompatibility between cloud.google.com/go/dataplex and google.golang.org/api; custom endpoints that aren't valid Dataplex API endpoints.

Related errors

• failed to initialize dataplex client: %w
• failed to get dataplex client: %w
• failed to list data scans: %w
• failed to list data products: code=%s message=%s
• failed to list data products: %w

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