{"record":{"id":"429558a810ce0e27","repo":"googleapis/mcp-toolbox","slug":"failed-to-get-documents-w","errorCode":null,"errorMessage":"failed to get documents: %w","messagePattern":"failed to get documents: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/sources/firestore/firestore.go","lineNumber":292,"sourceCode":"\t\t}\n\n\t\tmetricsData[\"executionStats\"] = executionStats\n\t}\n\n\treturn metricsData, nil\n}\n\nfunc (s *Source) GetDocuments(ctx context.Context, documentPaths []string) ([]any, error) {\n\t// Create document references from paths\n\tdocRefs := make([]*firestore.DocumentRef, len(documentPaths))\n\tfor i, path := range documentPaths {\n\t\tdocRefs[i] = s.FirestoreClient().Doc(path)\n\t}\n\n\t// Get all documents\n\tsnapshots, err := s.FirestoreClient().GetAll(ctx, docRefs)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to get documents: %w\", err)\n\t}\n\n\t// Convert snapshots to response data\n\tresults := make([]any, len(snapshots))\n\tfor i, snapshot := range snapshots {\n\t\tdocData := make(map[string]any)\n\t\tdocData[\"path\"] = documentPaths[i]\n\t\tdocData[\"exists\"] = snapshot.Exists()\n\n\t\tif snapshot.Exists() {\n\t\t\tdocData[\"data\"] = snapshot.Data()\n\t\t\tdocData[\"createTime\"] = snapshot.CreateTime\n\t\t\tdocData[\"updateTime\"] = snapshot.UpdateTime\n\t\t\tdocData[\"readTime\"] = snapshot.ReadTime\n\t\t}\n\n\t\tresults[i] = docData\n\t}","sourceCodeStart":274,"sourceCodeEnd":310,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/sources/firestore/firestore.go#L274-L310","documentation":"Thrown by Source.GetDocuments when FirestoreClient().GetAll(ctx, docRefs) fails while fetching documents by their paths. The raw client error is wrapped so the original gRPC status (permission denied, not found, invalid document path, unavailable) is preserved. It indicates the batch read itself failed, not result conversion.","triggerScenarios":"Calling GetDocuments with malformed document paths (wrong collection/document nesting depth, missing document ID segment), paths the caller has no permission to read, an unreachable Firestore backend, or FirestoreClient being uninitialized.","commonSituations":"IAM changes removing datastore.user from the service account, hand-constructed paths like 'users/' missing a document ID, pointing the source at a database id that doesn't exist, transient gRPC outages.","solutions":["Inspect the wrapped cause; if 'permission denied', grant roles/datastore.user to the service account.","Validate every path is a full doc path like collection/doc/collection2/doc2 — GetAll requires complete document paths.","Confirm the database id in the source config exists (gcloud firestore databases list).","If UNAVAILABLE/DEADLINE_EXCEEDED, retry with backoff or extend the context deadline.","Check project/network configuration (emulator vs production, quotas) if errors persist."],"exampleFix":"// before\npaths := []string{\"users/\"}\nres, err := source.GetDocuments(ctx, paths)\n// after\npaths := []string{\"users/user123\"}\nres, err := source.GetDocuments(ctx, paths)","handlingStrategy":"validation","validationCode":"// Go\nfunc validateDocPaths(paths []string) error {\n    for _, p := range paths {\n        if p == \"\" || strings.HasPrefix(p, \"/\") || strings.HasSuffix(p, \"/\") {\n            return fmt.Errorf(\"invalid document path %q\", p)\n        }\n        if len(strings.Split(p, \"/\"))%2 != 0 {\n            return fmt.Errorf(\"path %q has odd segments; a document id is missing\", p)\n        }\n    }\n    return nil\n}","typeGuard":"func isValidDocPath(p string) bool {\n    segs := strings.Split(p, \"/\")\n    return len(segs) >= 2 && len(segs)%2 == 0 && !slices.Contains(segs, \"\")\n}","tryCatchPattern":"snapshots, err := source.GetDocuments(ctx, paths)\nif err != nil {\n    if strings.Contains(err.Error(), \"permission denied\") {\n        return nil, fmt.Errorf(\"check service account IAM roles/datastore.user: %w\", err)\n    }\n    return nil, fmt.Errorf(\"get documents failed: %w\", err)\n}","preventionTips":["Build paths from typed references (client.Doc(...)) instead of string concatenation.","Verify IAM (roles/datastore.user) after service account rotation.","Validate document paths have an even number of non-empty segments before calling.","Set deadlines; retry UNAVAILABLE/DEADLINE_EXCEEDED with exponential backoff."],"tags":["firestore","batch-read","grpc","gcp"],"backgroundTag":"firestore-document-fetch-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"}