googleapis/mcp-toolbox · error

reference value must be a string

Error message

reference value must be a string

What it means

Type-check guard in JSONToFirestoreValue for referenceValue: the value is not a string, but a document reference must be expressed as a path string.

Source

Thrown at internal/tools/firestore/util/converter.go:147

								if err != nil {
									return nil, fmt.Errorf("map field %q: %w", k, err)
								}
								result[k] = converted
							}
							return result, nil
						}
					}
					return nil, fmt.Errorf("invalid map value format")
				case "referenceValue":
					// Convert to DocumentRef if client is provided
					if strVal, ok := val.(string); ok {
						if client != nil && isValidDocumentPath(strVal) {
							return client.Doc(strVal), nil
						}
						// Return the path as string if no client or invalid path
						return strVal, nil
					}
					return nil, fmt.Errorf("reference value must be a string")
				default:
					// If not a typed value, treat as regular map
					return convertPlainMap(v, client)
				}
			}
		}
		// Regular map without type annotation
		return convertPlainMap(v, client)
	default:
		// Plain values (for backward compatibility)
		return value, nil
	}
}

// convertPlainMap converts a plain map to Firestore format
func convertPlainMap(m map[string]any, client *firestore.Client) (map[string]any, error) {
	result := make(map[string]any)
	for k, v := range m {

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Send the document path as a string, e.g. 'users/alice'
2. Use mapValue or stringValue if the value is not a reference

When it happens

Trigger: Thrown at internal/tools/firestore/util/converter.go:147 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/9f42e378a10c5e05. Report an issue: GitHub.