googleapis/mcp-toolbox · error

failed to initialize dataplex client: %w

Error message

failed to initialize dataplex client: %w

What it means

This error wraps any failure that occurs while creating the Dataplex Catalog client for a BigQuery source. The source lazily initializes the Dataplex client via sync.Once, so the underlying connection error (from initDataplexConnection) is captured once and returned wrapped on every subsequent call. Common underlying causes are credential resolution failures, missing/invalid scopes, or failing to reach the Dataplex API endpoint.

Source

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

	_, ok := s.AllowedDatasets[targetDataset]
	return ok
}

func (s *Source) MakeDataplexCatalogClient() func() (*dataplexapi.CatalogClient, DataplexClientCreator, error) {
	return s.makeDataplexCatalogClient
}

func (s *Source) lazyInitDataplexClient(ctx context.Context, tracer trace.Tracer) func() (*dataplexapi.CatalogClient, DataplexClientCreator, error) {
	var once sync.Once
	var client *dataplexapi.CatalogClient
	var clientCreator DataplexClientCreator
	var err error

	return func() (*dataplexapi.CatalogClient, DataplexClientCreator, error) {
		once.Do(func() {
			c, cc, e := initDataplexConnection(ctx, tracer, s.Name, s.Project, s.UseClientAuthorization(), s.ImpersonateServiceAccount, s.Scopes)
			if e != nil {
				err = fmt.Errorf("failed to initialize dataplex client: %w", e)
				return
			}
			client = c

			// If using OAuth, wrap the provided client creator (cc) with caching logic
			if s.UseClientAuthorization() && cc != nil {
				clientCreator = func(tokenString string) (*dataplexapi.CatalogClient, error) {
					// Check cache
					if val, found := s.dataplexCache.Get(tokenString); found {
						return val.(*dataplexapi.CatalogClient), nil
					}

					// Cache miss - call client creator
					dpClient, err := cc(tokenString)
					if err != nil {
						return nil, err
					}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Run 'gcloud auth application-default login' or set GOOGLE_APPLICATION_CREDENTIALS to a valid service account key file
2. Verify the impersonation service account has roles/dataplex.catalogViewer (or Data Reader) on the target project and that scopes include the Dataplex scope
3. Check network access to dataplex.googleapis.com (proxy/firewall settings)
4. Confirm the configured project ID is correct and Dataplex API is enabled in the project

Example fix

// before
source:
  kind: bigquery
  project: my-project\n  # impersonateServiceAccount: missing@proj.iam.gserviceaccount.com\n// after\nsource:\n  kind: bigquery\n  project: my-project\n  impersonateServiceAccount: dataplex-reader@my-project.iam.gserviceaccount.com\n  # ensure GOOGLE_APPLICATION_CREDENTIALS points to valid credentials

// also verify Dataplex reachability
resp, err := http.Get("https://dataplex.googleapis.com")
_ = resp
if err != nil {
    return errors.New("dataplex endpoint unreachable from this environment")
}

client, cc, err := lazyDataplex()
if err != nil {
    if isInitErr(err) { return fallbackToNonDataplexPath() }
    return err
}

When it happens

Trigger: Calling tools that need Dataplex metadata (e.g. dataplex lookup for allowed datasets) when the source is configured with a Dataplex-dependent setup and initDataplexConnection fails: bad/missing GOOGLE_APPLICATION_CREDENTIALS, invalid impersonation service account, insufficient scopes, or network/DNS failure to the dataplex.googleapis.com endpoint.

Common situations: ADC not set up (no gcloud auth application-default login in dev), impersonated service account lacking the Dataplex Catalog Viewer role, project ID misconfigured, or corporate proxy/firewall blocking Google APIs.

Related errors

• failed to get dataplex client: %w
• failed to get catalog 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/9ee85f33ff380e68. Report an issue: GitHub.