{"record":{"id":"9ee85f33ff380e68","repo":"googleapis/mcp-toolbox","slug":"failed-to-initialize-dataplex-client-w","errorCode":null,"errorMessage":"failed to initialize dataplex client: %w","messagePattern":"failed to initialize dataplex client: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/sources/bigquery/bigquery.go","lineNumber":557,"sourceCode":"\t_, ok := s.AllowedDatasets[targetDataset]\n\treturn ok\n}\n\nfunc (s *Source) MakeDataplexCatalogClient() func() (*dataplexapi.CatalogClient, DataplexClientCreator, error) {\n\treturn s.makeDataplexCatalogClient\n}\n\nfunc (s *Source) lazyInitDataplexClient(ctx context.Context, tracer trace.Tracer) func() (*dataplexapi.CatalogClient, DataplexClientCreator, error) {\n\tvar once sync.Once\n\tvar client *dataplexapi.CatalogClient\n\tvar clientCreator DataplexClientCreator\n\tvar err error\n\n\treturn func() (*dataplexapi.CatalogClient, DataplexClientCreator, error) {\n\t\tonce.Do(func() {\n\t\t\tc, cc, e := initDataplexConnection(ctx, tracer, s.Name, s.Project, s.UseClientAuthorization(), s.ImpersonateServiceAccount, s.Scopes)\n\t\t\tif e != nil {\n\t\t\t\terr = fmt.Errorf(\"failed to initialize dataplex client: %w\", e)\n\t\t\t\treturn\n\t\t\t}\n\t\t\tclient = c\n\n\t\t\t// If using OAuth, wrap the provided client creator (cc) with caching logic\n\t\t\tif s.UseClientAuthorization() && cc != nil {\n\t\t\t\tclientCreator = func(tokenString string) (*dataplexapi.CatalogClient, error) {\n\t\t\t\t\t// Check cache\n\t\t\t\t\tif val, found := s.dataplexCache.Get(tokenString); found {\n\t\t\t\t\t\treturn val.(*dataplexapi.CatalogClient), nil\n\t\t\t\t\t}\n\n\t\t\t\t\t// Cache miss - call client creator\n\t\t\t\t\tdpClient, err := cc(tokenString)\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\treturn nil, err\n\t\t\t\t\t}\n","sourceCodeStart":539,"sourceCodeEnd":575,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/sources/bigquery/bigquery.go#L539-L575","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run 'gcloud auth application-default login' or set GOOGLE_APPLICATION_CREDENTIALS to a valid service account key file","Verify the impersonation service account has roles/dataplex.catalogViewer (or Data Reader) on the target project and that scopes include the Dataplex scope","Check network access to dataplex.googleapis.com (proxy/firewall settings)","Confirm the configured project ID is correct and Dataplex API is enabled in the project"],"exampleFix":"// before\nsource:\n  kind: bigquery\n  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","handlingStrategy":"validation","validationCode":"// also verify Dataplex reachability\nresp, err := http.Get(\"https://dataplex.googleapis.com\")\n_ = resp\nif err != nil {\n    return errors.New(\"dataplex endpoint unreachable from this environment\")\n}","typeGuard":null,"tryCatchPattern":"client, cc, err := lazyDataplex()\nif err != nil {\n    if isInitErr(err) { return fallbackToNonDataplexPath() }\n    return err\n}","preventionTips":["Pre-provision credentials via workload identity/ADC in production","Pin scopes explicitly in the source config to include Dataplex","Smoke-test Dataplex connectivity in CI","Remember the error is cached by sync.Once: restart the server after fixing credentials"],"tags":["gcp","dataplex","authentication","client-initialization"],"backgroundTag":"gcp-credential-resolution-failed","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}