googleapis/mcp-toolbox · error

failed to initialize Firebase Rules client: %w

Error message

failed to initialize Firebase Rules client: %w

What it means

Wrapped by Firestore Config.Initialize when initFirebaseRulesConnection fails to build the Firebase Rules API client (firebaserules service). Initialize closes the already-created Firestore client before returning, so this error aborts source startup entirely. It indicates the Google Cloud Rules API client could not be created — usually project/credentials/scope problems, not Firestore itself.

Source

Thrown at internal/sources/firestore/firestore.go:82

}

func (r Config) SourceConfigType() string {
	// Returns Firestore source type
	return SourceType
}

func (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {
	// Initializes a Firestore source
	client, err := initFirestoreConnection(ctx, tracer, r.Name, r.Project, r.Database)
	if err != nil {
		return nil, err
	}

	// Initialize Firebase Rules client
	rulesClient, err := initFirebaseRulesConnection(ctx, r.Project)
	if err != nil {
		client.Close()
		return nil, fmt.Errorf("failed to initialize Firebase Rules client: %w", err)
	}

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

var _ sources.Source = &Source{}

type Source struct {
	Config
	Client      *firestore.Client
	RulesClient *firebaserules.Service
}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Verify credentials: set GOOGLE_APPLICATION_CREDENTIALS or run under a service account with firebaserules permissions
2. Enable the Firebase Rules API (firebaserules.googleapis.com) on the project
3. Confirm the project id is correct and reachable (gcloud services list --enabled)
4. Check network egress to googleapis.com (proxy, Private Google Access, firewall rules)

Example fix

// before
rulesClient, err := initFirebaseRulesConnection(ctx, r.Project)
if err != nil {
    client.Close()
    return nil, fmt.Errorf("failed to initialize Firebase Rules client: %w", err)
}
// after
if r.Project == "" {
    client.Close()
    return nil, fmt.Errorf("project id is required for Firebase Rules client")
}
rulesClient, err := initFirebaseRulesConnection(ctx, r.Project)
if err != nil {
    client.Close()
    return nil, fmt.Errorf("failed to initialize Firebase Rules client (project=%s): %w", r.Project, err)
}

// Preflight GCP setup before Initialize
func preflightFirebaseRules(ctx context.Context, project string) error {
    if project == "" { return errors.New("project id required") }
    creds, err := google.FindDefaultCredentials(ctx, "https://www.googleapis.com/auth/firebase.service.managed")
    if err != nil { return fmt.Errorf("no valid Application Default Credentials: %w", err) }
    _ = creds
    return nil
}

func isRulesAPIUnavailable(err error) bool {
    s := err.Error()
    return strings.Contains(s, "has not been used") || strings.Contains(s, "is disabled") || strings.Contains(s, "403")
}

rulesClient, err := initFirebaseRulesConnection(ctx, r.Project)
if err != nil {
    client.Close()
    if isRulesAPIUnavailable(err) {
        return nil, fmt.Errorf("enable firebaserules.googleapis.com for project %s: %w", r.Project, err)
    }
    return nil, fmt.Errorf("failed to initialize Firebase Rules client: %w", err)
}

When it happens

Trigger: Initialize called with a Project whose Rules API is not enabled, Application Default Credentials missing or lacking the firebaserules scope, or the Rules service endpoint unreachable (network, restricted VIP, private Google access misconfig).

Common situations: GOOGLE_APPLICATION_CREDENTIALS unset in the environment; service account without Firebase Rules API permissions; FIREBASE_RULES_API not enabled on the project; running on-prem without route to googleapis.com; wrong project id in config.

Related errors

• failed to create Firestore client for project %q and databas
• unable to create bigtable.NewClient: %w
• error creating new sqladmin service: %w
• failed to find default Google Cloud credentials for project
• failed to create Firebase Rules client for project %q: %w

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