temporalio/temporal · error

invalid query filter

Error message

invalid query filter

What it means

Returned by GenerateSelectQuery when the supplied VisibilityReadFilter does not match any supported combination of query fields. The builder supports specific filter shapes (e.g. by RunID with Min/MaxTime, by business ID, open workflows, etc.); anything outside those combos is rejected before a SQL query is generated.

Source

Thrown at common/persistence/sql/sqlplugin/visibility.go:327

			fmt.Sprintf("%s <= ?", sadefs.GetSqlDbColName(timeAttr)),
			fmt.Sprintf(
				"((%s = ? AND %s > ?) OR %s < ?)",
				sadefs.GetSqlDbColName(timeAttr),
				sadefs.GetSqlDbColName(sadefs.RunID),
				sadefs.GetSqlDbColName(timeAttr),
			),
		)
		queryArgs = append(
			queryArgs,
			*filter.MinTime,
			*filter.MaxTime,
			*filter.MaxTime,
			*filter.RunID,
			*filter.MaxTime,
			*filter.PageSize,
		)
	default:
		return fmt.Errorf("invalid query filter")
	}

	filter.Query = fmt.Sprintf(
		`SELECT %s FROM executions_visibility
		WHERE %s
		ORDER BY %s DESC, %s
		LIMIT ?`,
		strings.Join(DbFields, ", "),
		strings.Join(whereClauses, " AND "),
		sadefs.GetSqlDbColName(timeAttr),
		sadefs.GetSqlDbColName(sadefs.RunID),
	)
	filter.QueryArgs = queryArgs
	return nil
}

View on GitHub (pinned to bde624efd1)

Solutions

1. Populate all required filter fields: set MinTime, MaxTime, and RunID (or the fields matching an intended supported case).
2. Check GenerateSelectQuery's switch in common/persistence/sql/sqlplugin/visibility.go:327 for the exact accepted filter shapes.
3. Use a higher-level visibility listing API instead of constructing raw filters manually.
4. If calling after an upgrade, update filter construction to the new filter struct semantics.

Example fix

// before
filter := &sqlplugin.VisibilityReadFilter{PageSize: 10} // missing time range/runID
// after
now := time.Now().UTC()
filter := &sqlplugin.VisibilityReadFilter{MinTime: &minT, MaxTime: &now, RunID: &runID, PageSize: 10}

// Go: verify filter completeness before the call
if filter.RunID == nil || filter.MinTime == nil || filter.MaxTime == nil {
    return fmt.Errorf("visibility filter requires RunID, MinTime and MaxTime")
}

// Go
if err != nil && strings.Contains(err.Error(), "invalid query filter") {
    return fmt.Errorf("unsupported visibility filter combination: %w", err)
}

When it happens

Trigger: Calling SelectFromVisibility with a filter whose fields don't form a recognized pattern — e.g. leaving required pointers nil (MinTime/MaxTime/RunID) so the switch falls to the default case, or mixing fields in a combination no case branch handles.

Common situations: Programmatically constructed filters with missing optional fields; API versions where filter fields changed (nil pointers after upgrade); calling visibility listing APIs with contradictory/insufficient filters.

Related errors

• requires a StartTime or CloseTime
• SearchPrecision is required when searching for a StartTime o
• where expression is nil
• where expression is nil
• link type is empty

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