googleapis/mcp-toolbox · error

invalid document path: must have an even number of segments

Error message

invalid document path: must have an even number of segments (e.g., 'collection/doc'), got %d segments

What it means

Parity guard in the shared Firestore path validator: a document path must have an even number of segments (alternating collection/document pairs); an odd count means the path ends on a collection, not a document.

Source

Thrown at internal/tools/firestore/util/validator.go:85

		return fmt.Errorf("path must be relative (e.g., '%s'), not absolute (matching pattern: ^projects/[^/]+/databases/[^/]+/documents/)", example)
	}

	// Split the path using strings.Split to preserve empty segments
	segments := strings.Split(path, "/")

	// Check for empty result
	if len(segments) == 0 {
		return fmt.Errorf("%s path cannot be empty or contain only slashes", pathTypeName)
	}

	// Check segment count based on path type
	segmentCount := len(segments)
	if pathType == CollectionPath && segmentCount%2 == 0 {
		// Collection paths must have an odd number of segments
		return fmt.Errorf("invalid collection path: must have an odd number of segments (e.g., 'collection' or 'collection/doc/subcollection'), got %d segments", segmentCount)
	} else if pathType == DocumentPath && segmentCount%2 != 0 {
		// Document paths must have an even number of segments
		return fmt.Errorf("invalid document path: must have an even number of segments (e.g., 'collection/doc'), got %d segments", segmentCount)
	}

	// Validate each segment
	for i, segment := range segments {
		isCollectionSegment := (i % 2) == 0
		if err := validateSegment(segment, isCollectionSegment); err != nil {
			return fmt.Errorf("invalid segment at position %d (%s): %w", i+1, segment, err)
		}
	}

	return nil
}

// validateSegment validates a single path segment
func validateSegment(segment string, isCollection bool) error {
	segmentType := "document ID"
	if isCollection {
		segmentType = "collection ID"

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Use an even-segment document path like 'users/alice'
2. Append the document ID if the path currently stops at a collection

When it happens

Trigger: Thrown at internal/tools/firestore/util/validator.go:85 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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