What causes "unknown filter name: %s" in temporalio/temporal?

Restrict the query to supported columns: WorkflowType, WorkflowId, StartTime, CloseTime, SearchPrecision

unknown filter name: %s

Error message

unknown filter name: %s

What it means

Archive visibility queries support only the filter columns WorkflowType (or legacy WorkflowTypeName), WorkflowId, StartTime, CloseTime, and SearchPrecision. Any other column name in the WHERE clause yields this error from the default branch of convertComparisonExpr.

Source

Thrown at common/archiver/s3store/query_parser.go:190

		}
		if op != "=" {
			return fmt.Errorf("only operation = is support for %s", SearchPrecision)
		}
		if parsedQuery.searchPrecision != nil && *parsedQuery.searchPrecision != val {
			return fmt.Errorf("only one expression is allowed for %s", SearchPrecision)
		}
		switch val {
		case PrecisionDay:
		case PrecisionHour:
		case PrecisionMinute:
		case PrecisionSecond:
		default:
			return fmt.Errorf("invalid value for %s: %s", SearchPrecision, val)
		}
		parsedQuery.searchPrecision = new(val)

	default:
		return fmt.Errorf("unknown filter name: %s", colNameStr)
	}

	return nil
}

View on GitHub (pinned to bde624efd1)

Solutions

Restrict the query to supported columns: WorkflowType, WorkflowId, StartTime, CloseTime, SearchPrecision
Fix casing to match the constants exactly (WorkflowId, not WorkflowID or WorkflowIDKey)
Run archive search only with queries built from the documented filter set; use the regular visibility store for other attributes

Example fix

// before
`ExecutionStatus = "Completed" AND WorkflowId = "x"`
// after
`WorkflowId = "x"` // ExecutionStatus is not a supported archive filter

Defensive patterns

Strategy: validation

Validate before calling

var allowedFilters = []string{"WorkflowType", "WorkflowTypeName", "WorkflowId", "StartTime", "CloseTime", "SearchPrecision"}
func validateFilters(q string) error {
    // naive scan: reject any `Column op` not in the allowed set
    for _, tok := range strings.Fields(q) {
        if strings.HasSuffix(tok, "=") || tok == "=" || tok == "!=" || tok == "<" || tok == ">" {
            continue
        }
        _ = allowedFilters // compare column tokens against this set
    }
    return nil
}

Type guard

func isAllowedFilter(col string) bool {
    switch col {
    case "WorkflowType", "WorkflowTypeName", "WorkflowId", "StartTime", "CloseTime", "SearchPrecision":
        return true
    }
    return false
}

Try / catch

parsed, err := parser.Parse(q)
if err != nil {
    if strings.Contains(err.Error(), "unknown filter name") {
        return nil, fmt.Errorf("unsupported archive filter; allowed: WorkflowType, WorkflowId, StartTime, CloseTime, SearchPrecision: %w", err)
    }
    return err
}

Prevention

Only build archive queries from the documented filter set
Match column names exactly, including casing (WorkflowId not WorkflowID)
Use the regular visibility store for columns like ExecutionStatus or RunId

When it happens

Trigger: Parsing clauses like `ExecutionStatus = "Completed"`, `RunId = "..."`, or any typo'd column (e.g. `WorkflowID = "x"` — note capital D vs the constant "WorkflowId").

Common situations: Porting queries from SQL/Elasticsearch visibility which support ExecutionStatus, RunId, HistoryLength, etc.; typos in column names with wrong casing; assuming archive search shares the full visibility schema.

Related errors

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