googleapis/mcp-toolbox · error

unable to create bigtable.NewClient: %w

Error message

unable to create bigtable.NewClient: %w

What it means

bigtable.NewClient — the data (read/write) client constructor — returned an error while the Bigtable source was being initialized. The constructor dials the Bigtable data API endpoint, so failures are typically bad project/instance identifiers or credential problems, not yet data-plane permission issues (those surface at query time).

Source

Thrown at internal/sources/bigtable/bigtable.go:232

	return out, nil
}

func initBigtableClient(ctx context.Context, tracer trace.Tracer, name, project, instance string) (*bigtable.Client, error) {
	//nolint:all // Reassigned ctx
	ctx, span := sources.InitConnectionSpan(ctx, tracer, SourceType, name)
	defer span.End()

	// Set up Bigtable data operations client.
	poolSize := 10
	userAgent, err := util.UserAgentFromContext(ctx)
	if err != nil {
		return nil, err
	}

	client, err := bigtable.NewClient(ctx, project, instance, option.WithUserAgent(userAgent), option.WithGRPCConnectionPool(poolSize))

	if err != nil {
		return nil, fmt.Errorf("unable to create bigtable.NewClient: %w", err)
	}

	return client, nil
}

func initBigtableInstanceAdminClient(ctx context.Context, tracer trace.Tracer, name, project string) (*bigtable.InstanceAdminClient, error) {
	//nolint:all // Reassigned ctx
	ctx, span := sources.InitConnectionSpan(ctx, tracer, SourceType, name)
	defer span.End()

	userAgent, err := util.UserAgentFromContext(ctx)
	if err != nil {
		return nil, err
	}

	client, err := bigtable.NewInstanceAdminClient(ctx, project, option.WithUserAgent(userAgent))
	if err != nil {
		return nil, fmt.Errorf("unable to create bigtable.NewInstanceAdminClient: %w", err)

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Set valid credentials: GOOGLE_APPLICATION_CREDENTIALS pointing to a service-account JSON, or `gcloud auth application-default login`
2. Verify `project` and `instance` in the source config match an existing Bigtable instance (`gcloud bigtable instances list`)
3. Check network access to bigtable.googleapis.com (proxy/firewall/VPC-SC)
4. Ensure ADC can be resolved in the runtime environment (GKE Workload Identity, metadata server, etc.)

Example fix

// before (env missing creds)
// GOOGLE_APPLICATION_CREDENTIALS unset
// after
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa-key.json

func preflightBigtableEnv(project, instance string) error {
	if os.Getenv("GOOGLE_APPLICATION_CREDENTIALS") == "" {
		if _, err := exec.LookPath("gcloud"); err == nil {
			out, err := exec.Command("gcloud", "auth", "application-default", "print-access-token").Output()
			if err != nil || len(out) == 0 {
				return fmt.Errorf("no Application Default Credentials available")
			}
		}
	}
	if project == "" || instance == "" {
		return fmt.Errorf("project and instance must be set in bigtable source config")
	}
	return nil
}

src, err := cfg.Initialize(ctx, tracer)
if err != nil {
	if strings.Contains(err.Error(), "unable to create client") || strings.Contains(err.Error(), "bigtable.NewClient") {
		// check credentials and project/instance IDs before retrying
	}
	return err
}

When it happens

Trigger: Source Initialize() calls initBigtableClient, which calls bigtable.NewClient(ctx, project, instance, option.WithUserAgent(...), option.WithGRPCConnectionPool(10)); the constructor returns non-nil error.

Common situations: Wrong `project` or `instance` in toolbox config; no Application Default Credentials (GOOGLE_APPLICATION_CREDENTIALS unset, no gcloud auth, running outside GCP without a service account); metadata server unreachable in non-GCP environments.

Related errors

• unable to create client: %w
• unable to create instance admin client: %w
• unable to create admin client: %w
• unable to create bigtable.NewInstanceAdminClient: %w
• unable to create bigtable.NewAdminClient: %w

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