{"record":{"id":"312f8798ec659af9","repo":"temporalio/temporal","slug":"invalid-task-schema-version","errorCode":null,"errorMessage":"invalid task schema version","messagePattern":"invalid task schema version","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"common/persistence/cassandra/matching_task_store_queue.go","lineNumber":33,"sourceCode":"\t\"go.temporal.io/server/common/primitives/timestamp\"\n)\n\n// matchingTaskVersion represents the task schema version\ntype matchingTaskVersion int\n\nconst (\n\tmatchingTaskVersion1 matchingTaskVersion = 1\n\tmatchingTaskVersion2 matchingTaskVersion = 2\n)\n\nvar switchTasksTableV1Cache sync.Map\n\n// switchTasksTable switches table names from tasks to tasks_v2 and modifies queries for v2 schema\nfunc switchTasksTable(baseQuery string, v matchingTaskVersion) string {\n\tif v == matchingTaskVersion2 {\n\t\treturn baseQuery\n\t} else if v != matchingTaskVersion1 {\n\t\tpanic(\"invalid task schema version\") // nolint:forbidigo // hardcoded constants\n\t}\n\n\tif v1query, ok := switchTasksTableV1Cache.Load(baseQuery); ok {\n\t\treturn v1query.(string) // nolint:revive\n\t}\n\n\tv1query := strings.ReplaceAll(baseQuery, \" tasks_v2 \", \" tasks \")\n\tv1query = strings.ReplaceAll(v1query, \" AND pass = 0 \", \" \")\n\tv1query = strings.ReplaceAll(v1query, \"type, pass, task_id\", \"type, task_id\")\n\tv1query = strings.ReplaceAll(v1query, \"?, 0, ?\", \"?, ?\")\n\n\tswitchTasksTableV1Cache.Store(baseQuery, v1query)\n\treturn v1query\n}\n\n// Task queue management queries, written for v2 (rewritten for v1 by switchTasksTable)\nconst (\n\ttemplateGetTaskQueueQuery = `SELECT ` +","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/common/persistence/cassandra/matching_task_store_queue.go#L15-L51","documentation":"switchTasksTable translates base Cassandra queries between the tasks and tasks_v2 table schemas based on the matchingTaskVersion. Only matchingTaskVersion1 and matchingTaskVersion2 are supported; any other version is a hard-coded-constant violation and panics. This protects against silently running queries against the wrong schema.","triggerScenarios":"Calling CreateTaskQueue, GetTaskQueue, UpdateTaskQueue, DeleteTaskQueue, or CreateTasks with a persisted task queue/version value that is neither v1 nor v2 — e.g. a corrupted or manually edited tasks row, or a new matchingTaskVersion constant introduced without extending this function.","commonSituations":"Version skew: persistence data written by a newer/older Temporal version using a different schema version; schema upgrade/rollback in Cassandra leaving rows with unexpected version markers; config pinning an unsupported version.","solutions":["Verify the matching task schema version in the persistence row/config is 1 or 2","Run the expected schema migrations (schema dir) so stored data matches the binary's supported versions","If a third version was added to the codebase, extend switchTasksTable to handle it","Check for binary/schema version skew during rolling upgrades and align deployment versions"],"exampleFix":"// before\n} else if v != matchingTaskVersion1 {\n\tpanic(\"invalid task schema version\")\n}\n// after\n} else if v != matchingTaskVersion1 {\n\treturn nil, serviceerror.NewInternal(fmt.Sprintf(\"invalid task schema version: %d\", v))\n}","handlingStrategy":"validation","validationCode":"if v := queue.GetMatchingTaskVersion(); v != matchingTaskVersion1 && v != matchingTaskVersion2 {\n\treturn fmt.Errorf(\"unsupported matching task schema version: %v\", v)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep binary and Cassandra schema versions aligned during rolling upgrades","Run required schema migrations before deploying new versions","Never hand-edit matching task rows or version markers in the DB","Test upgrade/rollback paths that change matchingTaskVersion"],"tags":["go","cassandra","persistence","schema-version","panic"],"backgroundTag":"schema-version-mismatch","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}