What causes "invalid search attribute type: %s" in temporalio/temporal?

Use exact IndexedValueType names: Int, Float, Bool, Keyword, Text, Datetime, KeywordList

invalid search attribute type: %s

Error message

invalid search attribute type: %s

What it means

Validation error when a PersistenceCustomSearchAttributes entry in the visibility config names a type that is not a known enumspb.IndexedValueType shorthand. The server maps config type names to IndexedValueType enums and aborts if the name is unrecognized.

Source

Thrown at temporal/fx.go:692

		MetricsHandler:             metricsHandler,
		Logger:                     logger,
		Serializer:                 serializer,
	})
	defer factory.Close()

	clusterMetadataManager, err := factory.NewClusterMetadataManager()
	if err != nil {
		return svc.ClusterMetadata, svc.Persistence, fmt.Errorf("error initializing cluster metadata manager: %w", err)
	}
	defer clusterMetadataManager.Close()

	visCSAOverride := map[enumspb.IndexedValueType]int{}
	for tpName, value := range svc.Visibility.PersistenceCustomSearchAttributes {
		saType, ok := enumspb.IndexedValueType_shorthandValue[tpName]
		if !ok {
			return svc.ClusterMetadata,
				svc.Persistence,
				fmt.Errorf("invalid search attribute type: %s", tpName)
		}
		if value < 0 || value > 99 {
			return svc.ClusterMetadata,
				svc.Persistence,
				fmt.Errorf(
					"invalid number of custom search attributes for type %s (must be between 0 and 99)",
					tpName,
				)
		}
		visCSAOverride[enumspb.IndexedValueType(saType)] = value
	}

	visDataStores := []config.DataStore{
		svc.Persistence.GetVisibilityStoreConfig(),
		svc.Persistence.GetSecondaryVisibilityStoreConfig(),
	}
	indexSearchAttributes := make(map[string]*persistencespb.IndexSearchAttributes)
	for _, ds := range visDataStores {

View on GitHub (pinned to bde624efd1)

Solutions

Use exact IndexedValueType names: Int, Float, Bool, Keyword, Text, Datetime, KeywordList
Check the key spelling against enumspb.IndexedValueType_shorthandValue
Validate config in CI before deploying

Example fix

// before
visibility:
  persistenceCustomSearchAttributes:
    CustomKeywordField: "keyword"
// after
visibility:
  persistenceCustomSearchAttributes:
    CustomKeywordField: "Keyword"

Defensive patterns

Strategy: validation

Validate before calling

valid := map[string]bool{
  "Int": true, "Float": true, "Bool": true,
  "Keyword": true, "Text": true, "Datetime": true, "KeywordList": true,
}
for name := range cfg.Visibility.PersistenceCustomSearchAttributes {
    if !valid[name] { return fmt.Errorf("bad SA type: %s", name) }
}

Prevention

Use enumspb IndexedValueType names exactly
Lint YAML config against a schema listing valid SA types
Copy type names from Temporal docs, not Elasticsearch terminology

When it happens

Trigger: Configuring Visibility.PersistenceCustomSearchAttributes with a key that is not a valid IndexedValueType name (e.g. misspelling, or Elasticsearch-style names like 'keyword' instead of 'Keyword').

Common situations: Typos in YAML config; copying type names from Elasticsearch mapping terminology ('keyword', 'long') instead of Temporal's enum names ('Keyword','Int'); upgrading Temporal and using a removed type name.

Related errors

AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01). Data as JSON: /api/errors/b3b94269d495eb7a. Report an issue: GitHub.