temporalio/temporal · error
%s has unsupported overlap policy %v
Error message
%s has unsupported overlap policy %v
What it means
Returned when a ScheduleOverlapPolicy value is not a recognized enum value in enumspb.ScheduleOverlapPolicy_name. This catches corrupted or out-of-range enum integers sent by clients, preventing undefined overlap behavior for schedule workflows.
Source
Thrown at service/frontend/workflow_handler.go:7053
func validateTimestamp(value *timestamppb.Timestamp, field string) error {
if value != nil {
if err := value.CheckValid(); err != nil {
return fmt.Errorf("%s is not a valid timestamp: %w", field, err)
}
}
return nil
}
func validateScheduleRemainingActions(schedule *schedulepb.Schedule) error {
if schedule.GetState().GetRemainingActions() < 0 {
return errors.New("remaining actions cannot be negative")
}
return nil
}
func validateScheduleOverlapPolicy(policy enumspb.ScheduleOverlapPolicy, field string) error {
if _, ok := enumspb.ScheduleOverlapPolicy_name[int32(policy)]; !ok {
return fmt.Errorf("%s has unsupported overlap policy %v", field, policy)
}
return nil
}
func (wh *WorkflowHandler) validateScheduleOverlapPolicies(
schedule *schedulepb.Schedule,
patch *schedulepb.SchedulePatch,
namespaceName string,
) error {
if schedule != nil {
if err := validateScheduleOverlapPolicy(schedule.GetPolicies().GetOverlapPolicy(), "schedule policies"); err != nil {
return wh.handleScheduleValidationError(err, scheduleValidationOverlapPolicy, namespaceName)
}
}
if patch == nil {
return nil
}
if trigger := patch.GetTriggerImmediately(); trigger != nil {View on GitHub (pinned to bde624efd1)
Solutions
- Use SDK enum constants (e.g. enumspb.SCHEDULE_OVERLAP_POLICY_SKIP) instead of raw ints
- Upgrade the server/SDK so proto versions align
- Default to UNSPECIFIED and let the server apply its default policy
Example fix
// before policy := enumspb.ScheduleOverlapPolicy(99) // after policy := enumspb.SCHEDULE_OVERLAP_POLICY_BUFFER_ALL
Defensive patterns
Strategy: validation
Validate before calling
if _, ok := enumspb.ScheduleOverlapPolicy_name[int32(policy)]; !ok { return fmt.Errorf("unsupported overlap policy %d", policy) } Type guard
func knownOverlapPolicy(p enumspb.ScheduleOverlapPolicy) bool { _, ok := enumspb.ScheduleOverlapPolicy_name[int32(p)]; return ok } Try / catch
if err := validateScheduleOverlapPolicy(policy, "overlap policy"); err != nil { return err } Prevention
- Use named enum constants only
- Keep SDK and server proto versions in sync
- Reject raw-int casts from external input
When it happens
Trigger: CreateSchedule/UpdateSchedule where SchedulePolicies.Overlap is set to an integer outside the known ScheduleOverlapPolicy range (e.g. raw enum value from a newer/older proto than the server supports).
Common situations: Proto/SDK version skew (server older than client enum); manually casting an int to the enum; corrupted persisted policy.
Understand the failure class
Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.
Related errors
- interval is not a valid duration: %w
- phase is not a valid duration: %w
- %s is not a valid timestamp: %w
- remaining actions cannot be negative
- batchParams is nil
AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01).
Data as JSON: /api/errors/b2fcce120dfa6e4e.
Report an issue: GitHub.