temporalio/temporal · error
Unknown task category type: %v
Error message
Unknown task category type: %v
What it means
getHistoryTasks dispatches a GetHistoryTasksRequest to immediate or scheduled task queries based on the request's task category. Only CategoryTypeImmediate and CategoryTypeScheduled exist in the enum; any other value means a corrupted request or a stale enum, and the store panics. It is an exhaustive-switch invariant over a closed enum.
Source
Thrown at common/persistence/cassandra/mutable_state_task_store.go:743
if err := iter.Close(); err != nil {
return nil, gocql.ConvertError(operation, err)
}
return response, nil
}
func (d *MutableStateTaskStore) getHistoryTasks(
ctx context.Context,
request *p.GetHistoryTasksRequest,
) (*p.InternalGetHistoryTasksResponse, error) {
switch request.TaskCategory.Type() {
case tasks.CategoryTypeImmediate:
return d.getHistoryImmedidateTasks(ctx, request)
case tasks.CategoryTypeScheduled:
return d.getHistoryScheduledTasks(ctx, request)
default:
panic(fmt.Sprintf("Unknown task category type: %v", request.TaskCategory.Type().String()))
}
}
func (d *MutableStateTaskStore) getHistoryImmedidateTasks(
ctx context.Context,
request *p.GetHistoryTasksRequest,
) (*p.InternalGetHistoryTasksResponse, error) {
// execution manager should already validated the request
// Reading history tasks need to be quorum level consistent, otherwise we could lose task
query := d.Session.Query(templateGetHistoryImmediateTasksQuery,
request.ShardID,
request.TaskCategory.ID(),
rowTypeHistoryTaskNamespaceID,
rowTypeHistoryTaskWorkflowID,
rowTypeHistoryTaskRunID,
defaultVisibilityTimestamp,
request.InclusiveMinTaskKey.TaskID,View on GitHub (pinned to bde624efd1)
Solutions
- Inspect how the GetHistoryTasksRequest was built and set TaskCategory to tasks.CategoryTypeImmediate or tasks.CategoryTypeScheduled
- Check for version skew: services running different versions of the tasks enum
- If a new category type was added, add a dispatch case to getHistoryTasks
- Ensure request constructors, not raw struct literals, are used to build requests
Example fix
// before
default:
panic(fmt.Sprintf("Unknown task category type: %v", request.TaskCategory.Type().String()))
// after
default:
return nil, serviceerror.NewInternal(fmt.Sprintf("unknown task category type: %v", request.TaskCategory.Type().String())) Defensive patterns
Strategy: validation
Validate before calling
if c := request.TaskCategory.Type(); c != tasks.CategoryTypeImmediate && c != tasks.CategoryTypeScheduled {
return fmt.Errorf("unsupported task category: %v", c.String())
} Prevention
- Build requests via constructors that set a valid TaskCategory, not raw struct literals
- Keep all services on compatible versions so the tasks enum cannot skew
- When adding a category type, update every exhaustive switch over the enum
When it happens
Trigger: Calling GetHistoryTasks with a request whose TaskCategory.Type() returns a value outside the two defined category types — e.g. a zero-value/nil-wrapped category or a request built by a mismatched proto version.
Common situations: Binary version skew between services sending new/unknown category values; constructing the request manually with an unset category; proto enum deserialization of an unknown value.
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
- unsupported partition kind:
- unable to decode cassandra serial consistency: %v
- invalid task schema version
- unknown workflow state: %v
- corrupted history event batch, wrong version and IDs
AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01).
Data as JSON: /api/errors/46f0d3236f2234b0.
Report an issue: GitHub.