{"record":{"id":"084245ff89ee4b39","repo":"googleapis/mcp-toolbox","slug":"failed-to-sample-documents-from-collection-q-w","errorCode":null,"errorMessage":"failed to sample documents from collection %q: %w","messagePattern":"failed to sample documents from collection %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/sources/firestore/firestore.go","lineNumber":643,"sourceCode":"\t\t}\n\t\tfor _, ref := range collRefs {\n\t\t\tcollectionsToInspect = append(collectionsToInspect, ref.ID)\n\t\t}\n\t}\n\n\tresult := make([]CollectionSchema, 0, len(collectionsToInspect))\n\tfor _, collName := range collectionsToInspect {\n\t\tschema, err := s.getSchemaFromPipeline(ctx, collName)\n\t\tif err == nil && len(schema.Fields) > 0 {\n\t\t\tresult = append(result, schema)\n\t\t\tcontinue\n\t\t}\n\n\t\t// Fallback: sample documents directly if get_schema pipeline stage is not available\n\t\tcollRef := s.FirestoreClient().Collection(collName)\n\t\tdocs, err := collRef.Limit(50).Documents(ctx).GetAll()\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to sample documents from collection %q: %w\", collName, err)\n\t\t}\n\n\t\tfieldsMap := make(map[string]map[string]bool)\n\n\t\tfor _, doc := range docs {\n\t\t\tdata := doc.Data()\n\t\t\textractFieldTypes(\"\", data, fieldsMap)\n\t\t}\n\n\t\tfields := make([]FieldSchema, 0, len(fieldsMap))\n\t\tfor fieldName, typeSet := range fieldsMap {\n\t\t\ttypesList := make([]string, 0, len(typeSet))\n\t\t\tfor t := range typeSet {\n\t\t\t\ttypesList = append(typesList, t)\n\t\t\t}\n\t\t\tfields = append(fields, FieldSchema{\n\t\t\t\tName:  fieldName,\n\t\t\t\tTypes: typesList,","sourceCodeStart":625,"sourceCodeEnd":661,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/sources/firestore/firestore.go#L625-L661","documentation":"This error is returned by GetSchema when the fallback path fires: the Firestore get_schema pipeline stage is unavailable, so the source samples up to 50 documents from the collection with collRef.Limit(50).Documents(ctx).GetAll(), and that read fails. The error wraps the underlying Firestore SDK error (permissions, missing collection, deadline, etc.) with the collection name for context.","triggerScenarios":"Calling GetSchema on a Firestore source when the get_schema pipeline stage is not supported/available and the direct document sampling query fails — e.g. the collection doesn't exist, the caller lacks datastore.documents.list/read permission, or ctx is cancelled/times out.","commonSituations":"IAM policies without Cloud Datastore User role; typos in the collection name; empty/new databases where the collection has no documents or the collection ID points to a parent-path-only collection; VPC/egress blocks preventing API access; context deadlines from slow projects.","solutions":["Verify the IAM identity has roles/datastore.user (or at least datastore.documents.list/read) on the project.","Confirm the collection name exists and is spelled exactly right (case-sensitive) in the Firestore console.","Check connectivity to firestore.googleapis.com and that ctx has an adequate deadline.","If the underlying error is permission-related, re-run with an authenticated ADC credential: gcloud auth application-default login."],"exampleFix":"// before: sampling fails on an empty/nonexistent collection\ndocs, err := collRef.Limit(50).Documents(ctx).GetAll()\n// after: ensure collection has readable documents and caller is authenticated first\nitr := s.FirestoreClient().Collection(collName).Limit(50).Documents(ctx)\ndocs, err := itr.GetAll()\nif err != nil {\n    if status.Code(err) == codes.NotFound {\n        return CollectionSchema{}, fmt.Errorf(\"collection %q does not exist: %w\", collName, err)\n    }\n    return nil, fmt.Errorf(\"failed to sample documents from collection %q: %w\", collName, err)\n}","handlingStrategy":"try-catch","validationCode":"// Go: verify access before calling GetSchema\nctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)\ndefer cancel()\nitr := client.Collection(\"my-collection\").Limit(1).Documents(ctx)\nif _, err := itr.Next(); err != nil {\n    return fmt.Errorf(\"cannot read collection before GetSchema: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"schema, err := src.GetSchema(ctx)\nif err != nil {\n    var opErr *googleapi.Error\n    if errors.As(err, &opErr) && (opErr.Code == 403 || opErr.Code == 401) {\n        // fix IAM / credentials, then retry\n    }\n    if status.Code(err) == codes.DeadlineExceeded {\n        // increase timeout or retry with backoff\n    }\n    return fmt.Errorf(\"schema discovery failed: %w\", err)\n}","preventionTips":["Grant the runtime identity roles/datastore.user before deploying.","Test collection readability with a 1-document probe call before schema discovery.","Always pass a context with a sensible timeout to GetSchema.","Verify collection names against the Firestore console rather than from memory."],"tags":["firestore","schema-discovery","permissions","document-sampling"],"backgroundTag":"firestore-document-read-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"}