{"record":{"id":"8a728740f0dcee17","repo":"googleapis/mcp-toolbox","slug":"failed-to-execute-query-w","errorCode":null,"errorMessage":"failed to execute query: %w","messagePattern":"failed to execute query: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/sources/firestore/firestore.go","lineNumber":217,"sourceCode":"\tPath       string         `json:\"path\"`\n\tData       map[string]any `json:\"data\"`\n\tCreateTime any            `json:\"createTime,omitempty\"`\n\tUpdateTime any            `json:\"updateTime,omitempty\"`\n\tReadTime   any            `json:\"readTime,omitempty\"`\n}\n\n// QueryResponse represents the full response including optional metrics\ntype QueryResponse struct {\n\tDocuments      []QueryResult  `json:\"documents\"`\n\tExplainMetrics map[string]any `json:\"explainMetrics,omitempty\"`\n}\n\n// ExecuteQuery runs the query and formats the results\nfunc (s *Source) ExecuteQuery(ctx context.Context, query *firestore.Query, analyzeQuery bool) (any, error) {\n\tdocIterator := query.Documents(ctx)\n\tdocs, err := docIterator.GetAll()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to execute query: %w\", err)\n\t}\n\t// Convert results to structured format\n\tresults := make([]QueryResult, len(docs))\n\tfor i, doc := range docs {\n\t\tresults[i] = QueryResult{\n\t\t\tID:         doc.Ref.ID,\n\t\t\tPath:       doc.Ref.Path,\n\t\t\tData:       doc.Data(),\n\t\t\tCreateTime: doc.CreateTime,\n\t\t\tUpdateTime: doc.UpdateTime,\n\t\t\tReadTime:   doc.ReadTime,\n\t\t}\n\t}\n\n\t// Return with explain metrics if requested\n\tif analyzeQuery {\n\t\texplainMetrics, err := getExplainMetrics(docIterator)\n\t\tif err == nil && explainMetrics != nil {","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/sources/firestore/firestore.go#L199-L235","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Read the wrapped cause (errors.Unwrap) — if it says 'requires an INDEX', create the composite index from the console link in the error message.","Check IAM: the service account needs roles/datastore.user on the project/database.","Verify the database is reachable: gcloud firestore databases describe, and that project/database id match the source config.","If the cause is DEADLINE_EXCEEDED/UNAVAILABLE, add retry with backoff or increase the context timeout.","Run 'gcloud firestore indexes composite list' to confirm all indexes deployed (index.yaml may be out of sync)."],"exampleFix":"// before\nresults, err := source.ExecuteQuery(ctx, query, false)\n// after\nresults, err := source.ExecuteQuery(ctx, query, false)\nif err != nil {\n    if strings.Contains(err.Error(), \"requires an INDEX\") {\n        return nil, fmt.Errorf(\"query needs a composite index: %w\", err)\n    }\n    return nil, err\n}","handlingStrategy":"try-catch","validationCode":"// Go\nfunc validateQueryTarget(coll string) error {\n    if coll == \"\" {\n        return errors.New(\"collection path is required\")\n    }\n    return nil\n}","typeGuard":"func isFirestoreIndexError(err error) bool {\n    return strings.Contains(err.Error(), \"requires an INDEX\")\n}","tryCatchPattern":"results, err := source.ExecuteQuery(ctx, query, false)\nif err != nil {\n    retryable := strings.Contains(err.Error(), \"UNAVAILABLE\") || strings.Contains(err.Error(), \"DEADLINE_EXCEEDED\")\n    return fmt.Errorf(\"firestore query failed (retryable=%v): %w\", retryable, err)\n}","preventionTips":["Create composite indexes for every where+orderBy combination before deploying the query.","Keep a versioned firestore.index.yaml and deploy indexes with the app.","Use context timeouts and retry transient gRPC statuses with backoff.","Test queries against the Firestore emulator in CI."],"tags":["firestore","query","grpc","gcp"],"backgroundTag":"firestore-query-failed","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}