From 31d6eb7d2d7942982fe73684976543c858569281 Mon Sep 17 00:00:00 2001 From: jmaeagle99 <44687433+jmaeagle99@users.noreply.github.com> Date: Wed, 1 Jul 2026 10:05:40 -0700 Subject: [PATCH 1/3] Add activity task failure cause --- openapi/openapiv2.json | 23 +++++++++++++++ openapi/openapiv3.yaml | 29 +++++++++++++++++++ temporal/api/enums/v1/failed_cause.proto | 13 +++++++++ temporal/api/history/v1/message.proto | 2 ++ .../workflowservice/v1/request_response.proto | 5 ++++ 5 files changed, 72 insertions(+) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 1437120e5..18e0f46a1 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -12225,6 +12225,10 @@ "deploymentOptions": { "$ref": "#/definitions/v1WorkerDeploymentOptions", "description": "Worker deployment options that user has set in the worker." + }, + "cause": { + "$ref": "#/definitions/v1ActivityTaskFailedCause", + "description": "Why did the task fail? When unset, the failure is treated as an unspecified activity failure." } } }, @@ -12250,6 +12254,10 @@ "resourceId": { "type": "string", "description": "Resource ID for routing. Contains \"workflow:workflow_id\" or \"activity:activity_id\" for standalone activities." + }, + "cause": { + "$ref": "#/definitions/v1ActivityTaskFailedCause", + "description": "Why did the activity task fail? Optional; when unset the failure is treated as a normal\nactivity failure. See the type's doc for more." } } }, @@ -14046,6 +14054,17 @@ } } }, + "v1ActivityTaskFailedCause": { + "type": "string", + "enum": [ + "ACTIVITY_TASK_FAILED_CAUSE_UNSPECIFIED", + "ACTIVITY_TASK_FAILED_CAUSE_GRPC_MESSAGE_TOO_LARGE", + "ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE", + "ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE" + ], + "default": "ACTIVITY_TASK_FAILED_CAUSE_UNSPECIFIED", + "description": "Activity tasks can fail for various reasons. Note that some of these reasons can only originate\nfrom the server, and some of them can only originate from the SDK/worker.\n\n - ACTIVITY_TASK_FAILED_CAUSE_GRPC_MESSAGE_TOO_LARGE: An activity task failed because a grpc message was too large.\n - ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE: An activity task failed because payloads were too large.\n - ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE: An activity task failed because an external storage operation failed.\nCheck the activity task failure message for more information." + }, "v1ActivityTaskFailedEventAttributes": { "type": "object", "properties": { @@ -14073,6 +14092,10 @@ "workerVersion": { "$ref": "#/definitions/v1WorkerVersionStamp", "title": "Version info of the worker who processed this workflow task.\nDeprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]" + }, + "cause": { + "$ref": "#/definitions/v1ActivityTaskFailedCause", + "description": "Why did the task fail? When unset, the failure is treated as an unspecified activity failure." } } }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 007d77168..bdd72bc1d 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -10227,6 +10227,15 @@ components: description: |- Version info of the worker who processed this workflow task. Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] + cause: + enum: + - ACTIVITY_TASK_FAILED_CAUSE_UNSPECIFIED + - ACTIVITY_TASK_FAILED_CAUSE_GRPC_MESSAGE_TOO_LARGE + - ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE + - ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE + type: string + description: Why did the task fail? When unset, the failure is treated as an unspecified activity failure. + format: enum ActivityTaskScheduledEventAttributes: type: object properties: @@ -15917,6 +15926,17 @@ components: resourceId: type: string description: Resource ID for routing. Contains "workflow:workflow_id" or "activity:activity_id" for standalone activities. + cause: + enum: + - ACTIVITY_TASK_FAILED_CAUSE_UNSPECIFIED + - ACTIVITY_TASK_FAILED_CAUSE_GRPC_MESSAGE_TOO_LARGE + - ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE + - ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE + type: string + description: |- + Why did the activity task fail? Optional; when unset the failure is treated as a normal + activity failure. See the type's doc for more. + format: enum RespondActivityTaskFailedByIdResponse: type: object properties: @@ -15969,6 +15989,15 @@ components: allOf: - $ref: '#/components/schemas/WorkerDeploymentOptions' description: Worker deployment options that user has set in the worker. + cause: + enum: + - ACTIVITY_TASK_FAILED_CAUSE_UNSPECIFIED + - ACTIVITY_TASK_FAILED_CAUSE_GRPC_MESSAGE_TOO_LARGE + - ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE + - ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE + type: string + description: Why did the task fail? When unset, the failure is treated as an unspecified activity failure. + format: enum RespondActivityTaskFailedResponse: type: object properties: diff --git a/temporal/api/enums/v1/failed_cause.proto b/temporal/api/enums/v1/failed_cause.proto index f8809fd4e..190089e81 100644 --- a/temporal/api/enums/v1/failed_cause.proto +++ b/temporal/api/enums/v1/failed_cause.proto @@ -92,6 +92,19 @@ enum WorkflowTaskFailedCause { WORKFLOW_TASK_FAILED_CAUSE_REQUEST_TOO_LARGE = 40; } +// Activity tasks can fail for various reasons. Note that some of these reasons can only originate +// from the server, and some of them can only originate from the SDK/worker. +enum ActivityTaskFailedCause { + ACTIVITY_TASK_FAILED_CAUSE_UNSPECIFIED = 0; + // An activity task failed because a grpc message was too large. + ACTIVITY_TASK_FAILED_CAUSE_GRPC_MESSAGE_TOO_LARGE = 1; + // An activity task failed because payloads were too large. + ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE = 2; + // An activity task failed because an external storage operation failed. + // Check the activity task failure message for more information. + ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE = 3; +} + enum StartChildWorkflowExecutionFailedCause { START_CHILD_WORKFLOW_EXECUTION_FAILED_CAUSE_UNSPECIFIED = 0; START_CHILD_WORKFLOW_EXECUTION_FAILED_CAUSE_WORKFLOW_ALREADY_EXISTS = 1; diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index 0211c6f55..b40324d68 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -517,6 +517,8 @@ message ActivityTaskFailedEventAttributes { // Version info of the worker who processed this workflow task. // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] temporal.api.common.v1.WorkerVersionStamp worker_version = 6 [deprecated = true]; + // Why did the task fail? When unset, the failure is treated as an unspecified activity failure. + temporal.api.enums.v1.ActivityTaskFailedCause cause = 7; } message ActivityTaskTimedOutEventAttributes { diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index c3dd95769..de1c271cd 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -739,6 +739,8 @@ message RespondActivityTaskFailedRequest { temporal.api.deployment.v1.Deployment deployment = 7 [deprecated = true]; // Worker deployment options that user has set in the worker. temporal.api.deployment.v1.WorkerDeploymentOptions deployment_options = 8; + // Why did the task fail? When unset, the failure is treated as an unspecified activity failure. + temporal.api.enums.v1.ActivityTaskFailedCause cause = 10; } message RespondActivityTaskFailedResponse { @@ -765,6 +767,9 @@ message RespondActivityTaskFailedByIdRequest { temporal.api.common.v1.Payloads last_heartbeat_details = 7; // Resource ID for routing. Contains "workflow:workflow_id" or "activity:activity_id" for standalone activities. string resource_id = 8; + // Why did the activity task fail? Optional; when unset the failure is treated as a normal + // activity failure. See the type's doc for more. + temporal.api.enums.v1.ActivityTaskFailedCause cause = 9; } message RespondActivityTaskFailedByIdResponse { From a79ad9ecd61f539be097e073067d641b6606c595 Mon Sep 17 00:00:00 2001 From: jmaeagle99 <44687433+jmaeagle99@users.noreply.github.com> Date: Wed, 12 Aug 2026 14:47:01 -0700 Subject: [PATCH 2/3] Update comments and drop gRPC too large value --- openapi/openapiv2.json | 3 +-- openapi/openapiv3.yaml | 3 --- temporal/api/enums/v1/failed_cause.proto | 13 +++++++------ 3 files changed, 8 insertions(+), 11 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 18e0f46a1..87358a0bd 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -14058,12 +14058,11 @@ "type": "string", "enum": [ "ACTIVITY_TASK_FAILED_CAUSE_UNSPECIFIED", - "ACTIVITY_TASK_FAILED_CAUSE_GRPC_MESSAGE_TOO_LARGE", "ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE", "ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE" ], "default": "ACTIVITY_TASK_FAILED_CAUSE_UNSPECIFIED", - "description": "Activity tasks can fail for various reasons. Note that some of these reasons can only originate\nfrom the server, and some of them can only originate from the SDK/worker.\n\n - ACTIVITY_TASK_FAILED_CAUSE_GRPC_MESSAGE_TOO_LARGE: An activity task failed because a grpc message was too large.\n - ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE: An activity task failed because payloads were too large.\n - ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE: An activity task failed because an external storage operation failed.\nCheck the activity task failure message for more information." + "description": "Activity tasks can fail for various reasons. Note that some of these reasons can only originate\nfrom the server, and some of them can only originate from the SDK/worker.\n\n - ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE: A payload-bearing field on a request the worker sent for this activity task exceeded the\nper-field size limit configured on the server for the namespace.\nCheck the activity task failure message for more information.\n - ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE: The worker failed to offload a payload to, or retrieve one from, external storage while\nprocessing this activity task.\nCheck the activity task failure message for more information." }, "v1ActivityTaskFailedEventAttributes": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index bdd72bc1d..a4560e13e 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -10230,7 +10230,6 @@ components: cause: enum: - ACTIVITY_TASK_FAILED_CAUSE_UNSPECIFIED - - ACTIVITY_TASK_FAILED_CAUSE_GRPC_MESSAGE_TOO_LARGE - ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE - ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE type: string @@ -15929,7 +15928,6 @@ components: cause: enum: - ACTIVITY_TASK_FAILED_CAUSE_UNSPECIFIED - - ACTIVITY_TASK_FAILED_CAUSE_GRPC_MESSAGE_TOO_LARGE - ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE - ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE type: string @@ -15992,7 +15990,6 @@ components: cause: enum: - ACTIVITY_TASK_FAILED_CAUSE_UNSPECIFIED - - ACTIVITY_TASK_FAILED_CAUSE_GRPC_MESSAGE_TOO_LARGE - ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE - ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE type: string diff --git a/temporal/api/enums/v1/failed_cause.proto b/temporal/api/enums/v1/failed_cause.proto index 190089e81..4ebe8c863 100644 --- a/temporal/api/enums/v1/failed_cause.proto +++ b/temporal/api/enums/v1/failed_cause.proto @@ -96,13 +96,14 @@ enum WorkflowTaskFailedCause { // from the server, and some of them can only originate from the SDK/worker. enum ActivityTaskFailedCause { ACTIVITY_TASK_FAILED_CAUSE_UNSPECIFIED = 0; - // An activity task failed because a grpc message was too large. - ACTIVITY_TASK_FAILED_CAUSE_GRPC_MESSAGE_TOO_LARGE = 1; - // An activity task failed because payloads were too large. - ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE = 2; - // An activity task failed because an external storage operation failed. + // A payload-bearing field on a request the worker sent for this activity task exceeded the + // per-field size limit configured on the server for the namespace. // Check the activity task failure message for more information. - ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE = 3; + ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE = 1; + // The worker failed to offload a payload to, or retrieve one from, external storage while + // processing this activity task. + // Check the activity task failure message for more information. + ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE = 2; } enum StartChildWorkflowExecutionFailedCause { From 92c6157f6b5fd24e79caca67d846ebec49a7a156 Mon Sep 17 00:00:00 2001 From: jmaeagle99 <44687433+jmaeagle99@users.noreply.github.com> Date: Fri, 14 Aug 2026 13:51:54 -0700 Subject: [PATCH 3/3] add activity worker unhandled failed cause --- openapi/openapiv2.json | 5 +++-- openapi/openapiv3.yaml | 3 +++ temporal/api/enums/v1/failed_cause.proto | 4 ++++ 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 87358a0bd..1ea891029 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -14059,10 +14059,11 @@ "enum": [ "ACTIVITY_TASK_FAILED_CAUSE_UNSPECIFIED", "ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE", - "ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE" + "ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE", + "ACTIVITY_TASK_FAILED_CAUSE_ACTIVITY_WORKER_UNHANDLED_FAILURE" ], "default": "ACTIVITY_TASK_FAILED_CAUSE_UNSPECIFIED", - "description": "Activity tasks can fail for various reasons. Note that some of these reasons can only originate\nfrom the server, and some of them can only originate from the SDK/worker.\n\n - ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE: A payload-bearing field on a request the worker sent for this activity task exceeded the\nper-field size limit configured on the server for the namespace.\nCheck the activity task failure message for more information.\n - ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE: The worker failed to offload a payload to, or retrieve one from, external storage while\nprocessing this activity task.\nCheck the activity task failure message for more information." + "description": "Activity tasks can fail for various reasons. Note that some of these reasons can only originate\nfrom the server, and some of them can only originate from the SDK/worker.\n\n - ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE: A payload-bearing field on a request the worker sent for this activity task exceeded the\nper-field size limit configured on the server for the namespace.\nCheck the activity task failure message for more information.\n - ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE: The worker failed to offload a payload to, or retrieve one from, external storage while\nprocessing this activity task.\nCheck the activity task failure message for more information.\n - ACTIVITY_TASK_FAILED_CAUSE_ACTIVITY_WORKER_UNHANDLED_FAILURE: The default cause for an activity task failure reported by a worker; a more specific cause\ntakes precedence whenever the condition is recognized.\nCheck the activity task failure message for more information." }, "v1ActivityTaskFailedEventAttributes": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index a4560e13e..ba2bf2efc 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -10232,6 +10232,7 @@ components: - ACTIVITY_TASK_FAILED_CAUSE_UNSPECIFIED - ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE - ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE + - ACTIVITY_TASK_FAILED_CAUSE_ACTIVITY_WORKER_UNHANDLED_FAILURE type: string description: Why did the task fail? When unset, the failure is treated as an unspecified activity failure. format: enum @@ -15930,6 +15931,7 @@ components: - ACTIVITY_TASK_FAILED_CAUSE_UNSPECIFIED - ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE - ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE + - ACTIVITY_TASK_FAILED_CAUSE_ACTIVITY_WORKER_UNHANDLED_FAILURE type: string description: |- Why did the activity task fail? Optional; when unset the failure is treated as a normal @@ -15992,6 +15994,7 @@ components: - ACTIVITY_TASK_FAILED_CAUSE_UNSPECIFIED - ACTIVITY_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE - ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE + - ACTIVITY_TASK_FAILED_CAUSE_ACTIVITY_WORKER_UNHANDLED_FAILURE type: string description: Why did the task fail? When unset, the failure is treated as an unspecified activity failure. format: enum diff --git a/temporal/api/enums/v1/failed_cause.proto b/temporal/api/enums/v1/failed_cause.proto index 4ebe8c863..c96de00db 100644 --- a/temporal/api/enums/v1/failed_cause.proto +++ b/temporal/api/enums/v1/failed_cause.proto @@ -104,6 +104,10 @@ enum ActivityTaskFailedCause { // processing this activity task. // Check the activity task failure message for more information. ACTIVITY_TASK_FAILED_CAUSE_EXTERNAL_STORAGE_FAILURE = 2; + // The default cause for an activity task failure reported by a worker; a more specific cause + // takes precedence whenever the condition is recognized. + // Check the activity task failure message for more information. + ACTIVITY_TASK_FAILED_CAUSE_ACTIVITY_WORKER_UNHANDLED_FAILURE = 3; } enum StartChildWorkflowExecutionFailedCause {