googleapis/mcp-toolbox · error

unable to create admin client: %w

Error message

unable to create admin client: %w

What it means

This error is wrapped during Bigtable source initialization after the data client and instance admin client were already created successfully. It means bigtable.NewAdminClient (used for table/schema admin operations) failed to construct. Since the two prior clients succeeded, this usually points at instance-level problems (bad instance ID) or intermittent credential/API failures.

Source

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

}

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,
		InstanceAdmin: instanceAdminClient,
		Admin:         adminClient,
	}
	return s, nil
}

var _ sources.Source = &Source{}

type Source struct {
	Config
	Client        *bigtable.Client
	InstanceAdmin *bigtable.InstanceAdminClient
	Admin         *bigtable.AdminClient

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Verify the `instance` field in the bigtable source config matches an existing Bigtable instance ID (`gcloud bigtable instances list --project=<project>`)
2. Verify the `project` ID is correct and Application Default Credentials are valid (`gcloud auth application-default login`)
3. Check network connectivity / VPC-SC / proxy settings that could block the Bigtable admin API endpoint
4. Retry initialization — gRPC dial failures can be transient

Example fix

// before
sources:
  my-bt:
    type: bigtable
    project: my-project
    instance: prod-instnace   # typo
// after
sources:
  my-bt:
    type: bigtable
    project: my-project
    instance: prod-instance

func validateBigtableInstance(ctx context.Context, project, instance string) error {
	if project == "" || instance == "" {
		return fmt.Errorf("project and instance are required")
	}
	// verify instance exists before building the source
	c, err := gax.NewHTTPClient()
	_ = c
	out, err := exec.Command("gcloud", "bigtable", "instances", "describe", instance, "--project", project).CombinedOutput()
	if err != nil {
		return fmt.Errorf("instance %q not found in project %q: %v: %s", instance, project, err, out)
	}
	return nil
}

if adminClient, ok := err.(*googleapi.Error); ok && adminClient.Code == 404 { /* instance missing */ }

s, err := cfg.Initialize(ctx, tracer)
if err != nil {
	var gerr *googleapi.Error
	if errors.As(err, &gerr) {
		log.Printf("bigtable admin init failed: code=%d msg=%s", gerr.Code, gerr.Message)
	}
	return err
}

When it happens

Trigger: Source Initialize() calls initBigtableAdminClient, which invokes bigtable.NewAdminClient(ctx, project, instance, option.WithUserAgent(userAgent)); the constructor returns a non-nil error.

Common situations: Wrong `instance` value in the toolbox config (data and instance-admin clients succeeded because they tolerate/validate differently, but the admin client rejects the instance ID); the instance was deleted or renamed; transient gRPC/network failure; partially-scoped credentials failing admin endpoint checks.

Related errors

• unable to create client: %w
• unable to create instance admin client: %w
• unable to create bigtable.NewClient: %w
• unable to create bigtable.NewAdminClient: %w
• toolbox failed to initialize: %w

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