googleapis/mcp-toolbox · error

failed to execute query: %w

Error message

failed to execute query: %w

What it means

This error is thrown by Source.ExecuteQuery in internal/sources/firestore/firestore.go when the underlying Cloud Firestore query fails. The Google Cloud Firestore Go client's iterator (query.Documents(ctx).GetAll()) returned an error, which is wrapped with %w so callers can inspect the original cause via errors.As/Is. It means the query itself (not parameter parsing or auth in the toolbox layer) failed at the Firestore backend.

Source

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

	Path       string         `json:"path"`
	Data       map[string]any `json:"data"`
	CreateTime any            `json:"createTime,omitempty"`
	UpdateTime any            `json:"updateTime,omitempty"`
	ReadTime   any            `json:"readTime,omitempty"`
}

// QueryResponse represents the full response including optional metrics
type QueryResponse struct {
	Documents      []QueryResult  `json:"documents"`
	ExplainMetrics map[string]any `json:"explainMetrics,omitempty"`
}

// ExecuteQuery runs the query and formats the results
func (s *Source) ExecuteQuery(ctx context.Context, query *firestore.Query, analyzeQuery bool) (any, error) {
	docIterator := query.Documents(ctx)
	docs, err := docIterator.GetAll()
	if err != nil {
		return nil, fmt.Errorf("failed to execute query: %w", err)
	}
	// Convert results to structured format
	results := make([]QueryResult, len(docs))
	for i, doc := range docs {
		results[i] = QueryResult{
			ID:         doc.Ref.ID,
			Path:       doc.Ref.Path,
			Data:       doc.Data(),
			CreateTime: doc.CreateTime,
			UpdateTime: doc.UpdateTime,
			ReadTime:   doc.ReadTime,
		}
	}

	// Return with explain metrics if requested
	if analyzeQuery {
		explainMetrics, err := getExplainMetrics(docIterator)
		if err == nil && explainMetrics != nil {

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Read the wrapped cause (errors.Unwrap) — if it says 'requires an INDEX', create the composite index from the console link in the error message.
2. Check IAM: the service account needs roles/datastore.user on the project/database.
3. Verify the database is reachable: gcloud firestore databases describe, and that project/database id match the source config.
4. If the cause is DEADLINE_EXCEEDED/UNAVAILABLE, add retry with backoff or increase the context timeout.
5. Run 'gcloud firestore indexes composite list' to confirm all indexes deployed (index.yaml may be out of sync).

Example fix

// before
results, err := source.ExecuteQuery(ctx, query, false)
// after
results, err := source.ExecuteQuery(ctx, query, false)
if err != nil {
    if strings.Contains(err.Error(), "requires an INDEX") {
        return nil, fmt.Errorf("query needs a composite index: %w", err)
    }
    return nil, err
}

// Go
func validateQueryTarget(coll string) error {
    if coll == "" {
        return errors.New("collection path is required")
    }
    return nil
}

func isFirestoreIndexError(err error) bool {
    return strings.Contains(err.Error(), "requires an INDEX")
}

results, err := source.ExecuteQuery(ctx, query, false)
if err != nil {
    retryable := strings.Contains(err.Error(), "UNAVAILABLE") || strings.Contains(err.Error(), "DEADLINE_EXCEEDED")
    return fmt.Errorf("firestore query failed (retryable=%v): %w", retryable, err)
}

When it happens

Trigger: Calling ExecuteQuery with a query that requires a missing composite index (unindexed range filter + orderBy), invalid cursors, a query on a collection the caller cannot read, or an unreachable Firestore backend (gRPC UNAVAILABLE/DEADLINE_EXCEEDED).

Common situations: Missing composite index for an orderBy + where combination (Firestore returns 'The query requires an INDEX'), running queries against a database the service account lacks read access to, regional/database-id misconfiguration in the source config, transient gRPC outages under load.

Related errors

• failed to get documents: %w
• failed to add document: %w
• failed to retrieve updated document: %w
• failed to update document: %w
• failed to create Dataplex client for project %q: %w

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