googleapis/mcp-toolbox · error

failed to sample documents from collection %q: %w

Error message

failed to sample documents from collection %q: %w

What it means

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.

Source

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

		}
		for _, ref := range collRefs {
			collectionsToInspect = append(collectionsToInspect, ref.ID)
		}
	}

	result := make([]CollectionSchema, 0, len(collectionsToInspect))
	for _, collName := range collectionsToInspect {
		schema, err := s.getSchemaFromPipeline(ctx, collName)
		if err == nil && len(schema.Fields) > 0 {
			result = append(result, schema)
			continue
		}

		// Fallback: sample documents directly if get_schema pipeline stage is not available
		collRef := s.FirestoreClient().Collection(collName)
		docs, err := collRef.Limit(50).Documents(ctx).GetAll()
		if err != nil {
			return nil, fmt.Errorf("failed to sample documents from collection %q: %w", collName, err)
		}

		fieldsMap := make(map[string]map[string]bool)

		for _, doc := range docs {
			data := doc.Data()
			extractFieldTypes("", data, fieldsMap)
		}

		fields := make([]FieldSchema, 0, len(fieldsMap))
		for fieldName, typeSet := range fieldsMap {
			typesList := make([]string, 0, len(typeSet))
			for t := range typeSet {
				typesList = append(typesList, t)
			}
			fields = append(fields, FieldSchema{
				Name:  fieldName,
				Types: typesList,

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Verify the IAM identity has roles/datastore.user (or at least datastore.documents.list/read) on the project.
2. Confirm the collection name exists and is spelled exactly right (case-sensitive) in the Firestore console.
3. Check connectivity to firestore.googleapis.com and that ctx has an adequate deadline.
4. If the underlying error is permission-related, re-run with an authenticated ADC credential: gcloud auth application-default login.

Example fix

// before: sampling fails on an empty/nonexistent collection
docs, err := collRef.Limit(50).Documents(ctx).GetAll()
// after: ensure collection has readable documents and caller is authenticated first
itr := s.FirestoreClient().Collection(collName).Limit(50).Documents(ctx)
docs, err := itr.GetAll()
if err != nil {
    if status.Code(err) == codes.NotFound {
        return CollectionSchema{}, fmt.Errorf("collection %q does not exist: %w", collName, err)
    }
    return nil, fmt.Errorf("failed to sample documents from collection %q: %w", collName, err)
}

// Go: verify access before calling GetSchema
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
itr := client.Collection("my-collection").Limit(1).Documents(ctx)
if _, err := itr.Next(); err != nil {
    return fmt.Errorf("cannot read collection before GetSchema: %w", err)
}

schema, err := src.GetSchema(ctx)
if err != nil {
    var opErr *googleapi.Error
    if errors.As(err, &opErr) && (opErr.Code == 403 || opErr.Code == 401) {
        // fix IAM / credentials, then retry
    }
    if status.Code(err) == codes.DeadlineExceeded {
        // increase timeout or retry with backoff
    }
    return fmt.Errorf("schema discovery failed: %w", err)
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• failed to marshal schema query: %w
• get_schema API error (status %d): %s
• Toolbox binary not found
• HTTP error! status: ${response.status}
• Invalid number input for ${NAME}: ${RAW_VALUE}

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