googleapis/mcp-toolbox · error

failed to create Dataplex client for project

Error message

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

What it means

After resolving client options (impersonated or default credentials), the source constructs the Dataplex Catalog client with dataplexapi.NewCatalogClient. This error wraps that constructor's failure, which is typically a transport/endpoint or credential-option problem rather than a project-level permission issue. No other clients exist yet, so nothing else needs closing on this path.

Solutions

  1. Verify network access to dataplex.googleapis.com (DNS, firewall, proxy) from the host running the toolbox.
  2. Re-authenticate: refresh ADC (`gcloud auth application-default login`) or fix the credentials file, then retry.
  3. Update cloud.google.com/go/dataplex to the latest version.
  4. Unset conflicting env vars (GOOGLE_API_USE_MTLS_ENDPOINT, endpoint overrides) unless intentionally configured.
  5. If impersonation was just added, first confirm the impersonated token source works (fix error 693 first).
Defensive patterns

Strategy: try-catch

Validate before calling

curl -sS --max-time 5 https://dataplex.googleapis.com/ >/dev/null && echo reachable || echo unreachable

Try / catch

src, err := cfg.Initialize(ctx, tracer)
if err != nil {
	if strings.Contains(err.Error(), "failed to create Dataplex client") {
		log.Printf("transient Dataplex client failure, retrying: %v", err)
		return retryWithBackoff(func() error { _, err := cfg.Initialize(ctx, tracer); return err })
	}
	return err
}

Prevention

When it happens

Trigger: initDataplexConnection calls dataplexapi.NewCatalogClient(ctx, opts...) and it errors — usually due to invalid client options, unreachable dataplex.googleapis.com endpoint, or gRPC transport setup failure.

Common situations: Corporate proxy blocking dataplex.googleapis.com; custom GOOGLE_API_USE_MTLS_ENDPOINT or emulator env misconfiguration; corrupted ADC credentials object passed via option.WithCredentials; out-of-date cloud.google.com/go/dataplex library.

Related errors

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

Appendix: source

Thrown at internal/sources/dataplex/dataplex.go:229

		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, nil, nil, fmt.Errorf("failed to find default Google Cloud credentials for project %q: %w", project, err)
		}
		opts = []option.ClientOption{
			option.WithUserAgent(userAgent),
			option.WithCredentials(cred),
		}
	}

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

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

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

	projectsClient, err := resourcemanager.NewProjectsClient(ctx, opts...)
	if err != nil {
		client.Close()

View on GitHub (pinned to 8cc6e09de2)