googleapis/mcp-toolbox · critical

unable to create client: %w

Error message

unable to create client: %w

What it means

Config.Initialize fails when initBigtableClient cannot construct the Bigtable data client (cloud.google.com/go/bigtable.NewClient). Causes include invalid project/instance IDs, missing or invalid Application Default Credentials, unreachable Google endpoints, or unsupported configuration. The data client is not created, so the source cannot start.

Source

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

	}
	return actual, nil
}

type Config struct {
	Name     string `yaml:"name" validate:"required"`
	Type     string `yaml:"type" validate:"required"`
	Project  string `yaml:"project" validate:"required"`
	Instance string `yaml:"instance" validate:"required"`
}

func (r Config) SourceConfigType() string {
	return SourceType
}

func (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {
	client, err := initBigtableClient(ctx, tracer, r.Name, r.Project, r.Instance)
	if err != nil {
		return nil, fmt.Errorf("unable to create client: %w", err)
	}

	instanceAdminClient, err := initBigtableInstanceAdminClient(ctx, tracer, r.Name, r.Project)
	if err != nil {
		client.Close()
		return nil, fmt.Errorf("unable to create instance admin client: %w", err)
	}

	adminClient, err := initBigtableAdminClient(ctx, tracer, r.Name, r.Project, r.Instance)
	if err != nil {
		client.Close()
		instanceAdminClient.Close()
		return nil, fmt.Errorf("unable to create admin client: %w", err)
	}

	s := &Source{
		Config:        r,
		Client:        client,

View on GitHub (pinned to 8cc6e09de2)

Solutions

  1. Set valid credentials: export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json or run gcloud auth application-default login
  2. Verify project and instance fields in the toolbox config against gcloud config list / gcloud bigtable instances list
  3. Check network egress to *.googleapis.com (oauth2.googleapis.com, bigtable.googleapis.com)
  4. Fix the wrapped error by inspecting it: it contains the precise reason (credential, permission, or not-found)

Example fix

// before: source config missing instance
kind: bigtable
project: my-project
// after: complete config with credentials available
kind: bigtable
project: my-project
instance: my-instance
// plus: gcloud auth application-default login
Defensive patterns

Strategy: validation

Validate before calling

// run before starting the toolbox
func precheckBigtable(ctx context.Context, project, instance string) error {
    if project == "" || instance == "" {
        return fmt.Errorf("bigtable source requires non-empty project and instance; got project=%q instance=%q", project, instance)
    }
    creds, err := google.FindDefaultCredentials(ctx, bigtable.Scope)
    if err != nil {
        return fmt.Errorf("no ADC found: set GOOGLE_APPLICATION_CREDENTIALS or run 'gcloud auth application-default login': %w", err)
    }
    return nil
}

Type guard

func isAuthError(err error) bool {
    c := status.Code(errors.Unwrap(err))
    return c == codes.Unauthenticated || c == codes.PermissionDenied
}

Try / catch

src, err := cfg.Initialize(ctx, tracer)
if err != nil {
    var preErr error
    if errors.Unwrap(err) != nil { preErr = errors.Unwrap(err) }
    if preErr != nil && isAuthError(preErr) {
        return fmt.Errorf("fix credentials (GOOGLE_APPLICATION_CREDENTIALS / gcloud auth): %w", err)
    }
    return err
}

Prevention

When it happens

Trigger: Source initialization (toolbox startup with a bigtable source config) when: r.Project or r.Instance is empty/malformed, ADC are absent (no GOOGLE_APPLICATION_CREDENTIALS, no metadata server), token fetching fails, or the underlying NewClient RPC to list the instance returns an error.

Common situations: First-time local setup without gcloud auth application-default login; wrong project ID in YAML config; running outside GCP without a service-account key file; VPC/DMZ network blocking googleapis.com; deleted instance still referenced in config.

Related errors

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