googleapis/mcp-toolbox · critical

unable to create instance admin client: %w

Error message

unable to create instance admin client: %w

What it means

Config.Initialize fails when initBigtableInstanceAdminClient cannot create the Bigtable InstanceAdmin client. The data client was already created successfully (and is Close()d before returning), so the failure is specific to the instance-admin client: credentials, project ID validity, or endpoint/network issues. Initialization aborts, leaving the source unusable.

Source

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

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

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Verify credentials exist and are valid (GOOGLE_APPLICATION_CREDENTIALS or gcloud auth application-default login); note the error fires after the data client succeeded, so check project-scoped permissions specifically
2. Confirm r.Project is correct and exists (gcloud projects describe)
3. Grant roles/bigtable.admin on the project to the service account
4. Check network access to bigtableadmin.googleapis.com and oauth2.googleapis.com
5. Inspect the wrapped error (%w) for the precise gRPC code (Unauthenticated, PermissionDenied, NotFound)

Example fix

// before: project field wrong, admin client creation fails
kind: bigtable
project: my-projekt
instance: my-instance
// after
kind: bigtable
project: my-project
instance: my-instance

// validate project before Initialize; instance-admin client requires a valid project
func precheckProject(ctx context.Context, project string) error {
    if project == "" {
        return errors.New("project must be set for the bigtable instance admin client")
    }
    if _, err := crmService.Projects.Get(project).Context(ctx).Do(); err != nil {
        return fmt.Errorf("project %q not reachable: %w", project, err)
    }
    return nil
}

func isPermissionDenied(err error) bool {
    return status.Code(errors.Unwrap(err)) == codes.PermissionDenied
}

src, err := cfg.Initialize(ctx, tracer)
if err != nil && strings.Contains(err.Error(), "instance admin client") {
    if isPermissionDenied(err) {
        return fmt.Errorf("grant roles/bigtable.admin on project %q to the service account: %w", project, err)
    }
    return err
}

When it happens

Trigger: Source initialization when: bigtable.NewInstanceAdminClient fails due to missing ADC, invalid r.Project (empty or nonexistent project), IAM permission to query the project is absent, or network egress to bigtableadmin.googleapis.com / oauth2 endpoints is blocked.

Common situations: Service account valid for data access but lacking project-level Bigtable admin roles; typo'd project ID; local runs without credentials; proxy/firewall blocking bigtableadmin.googleapis.com while allowing the data endpoint; stale or revoked key files.

Related errors

• unable to create client: %w
• error getting email from ADC: %v
• failed to create impersonated credentials for %q: %w
• failed to update cluster: %w
• failed to delete cluster: %w

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