googleapis/mcp-toolbox · error

unable to create client: %w

Error message

unable to create client: %w

What it means

CloudStorage Config.Initialize creates a Google Cloud Storage client via initGCSClient (project-scoped, with tracing). Any failure constructing the client — bad ADC, invalid project, network/API errors — is wrapped with this message. The source cannot be registered without a working GCS client.

Source

Thrown at internal/sources/cloudstorage/cloudstorage.go:78

	return actual, nil
}

type Config struct {
	Name              string   `yaml:"name" validate:"required"`
	Type              string   `yaml:"type" validate:"required"`
	Project           string   `yaml:"project" validate:"required"`
	AllowedBuckets    []string `yaml:"allowedBuckets,omitempty"`
	AllowedLocalRoots []string `yaml:"allowedLocalRoots,omitempty"`
}

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

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

	s := &Source{
		Config: r,
		client: client,
	}
	return s, nil
}

var _ sources.Source = &Source{}

type Source struct {
	Config
	client *storage.Client
}

func (s *Source) validateBucket(bucket string) error {
	if len(s.AllowedBuckets) == 0 {

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Authenticate: run 'gcloud auth application-default login' or set GOOGLE_APPLICATION_CREDENTIALS to a valid key file.
2. Verify the 'project' field in the source config matches a real, billing-enabled project.
3. Ensure storage.googleapis.com is reachable and the Cloud Storage API is enabled.
4. Grant the identity storage-related roles (e.g. roles/storage.admin or objectViewer) as needed.

Example fix

// before: no credentials
// after:
//   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa-key.json
// or gcloud auth application-default login

creds, err := google.FindDefaultCredentials(ctx, storage.ScopeFullControl)
if err != nil {
    return fmt.Errorf("GCS auth missing: %w", err)
}

if err := toolbox.Start(ctx); err != nil {
    if strings.Contains(err.Error(), "unable to create client") {
        // check ADC, project id, and network before retrying
    }
    return err
}

When it happens

Trigger: Initializing a cloud-storage source where storage.NewClient fails: missing/invalid Application Default Credentials, invalid 'project' id, Cloud Storage API disabled, or outbound network blocked (e.g. PRIVATE_IP options in an unsupported environment).

Common situations: Running locally without gcloud ADC; wrong project id in config; firewalled environment blocking googleapis.com; quota/billing not enabled on the project.

Related errors

• ErrReadSizeLimitExceeded
• ErrBinaryContent
• ErrDestinationExists
• error creating client from ADC: %w
• error getting email from ADC: %v

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