Functions v4 client: terminal/invalid-state control-plane ops surface opaque `2 UNKNOWN` (HTTP 400) instead of a meaningful status

[YunchuWang]

Summary

A Durable Functions v4 (durable-functions@0.4.x, gRPC-core) client calling a control-plane op (terminate/suspend/resume) on an instance in a terminal state (Completed/Failed/Terminated) currently gets an opaque 2 UNKNOWN: Exception was thrown by handler, which the compat turns into HTTP 400. v3 (extension-HTTP path) instead swallowed terminal-instance ops -> HTTP 200 (no-op).

Evidence (E2E run-2)

• Nonexistent instance -> 5 NOT_FOUND (rich detail) — handled in Add durable-functions@4.0.0 — Azure Functions Durable provider on the gRPC core (+ core host helpers, E2E CI, and release pipeline) #282.
• Terminal instance -> 2 UNKNOWN: Exception was thrown by handler (client sees NO detail). Host log shows Cannot <op> ... in the <State> state. but it is not propagated over gRPC.

Problems

1. Server-side: the extension's gRPC endpoint maps a wrong-state InvalidOperationException to opaque 2 UNKNOWN, losing the reason. Ideally return a meaningful status (e.g. FAILED_PRECONDITION) with detail — benefits ALL language SDKs.
2. Client-side (compat): without server detail, v4 can't distinguish terminal from other states without an extra getStatus round-trip; the current bare 400 is not ideal (should distinguish 404 nonexistent from a terminal/conflict status, and not be a plain 400).

Proposed direction (needs decision)

• Prefer a server-side fix (extension gRPC returns meaningful code+detail).
• Client interim: getStatus->runtimeStatus, then terminal (swallow->200 or 409/410) vs invalid-non-terminal (400 + Cannot <op> in <State>). Decide exact policy — reason this is separate from Add durable-functions@4.0.0 — Azure Functions Durable provider on the gRPC core (+ core host helpers, E2E CI, and release pipeline) #282.

Scope

3 e2e specs skipped in #282 pending this: suspend-completed, terminate-completed, terminate-terminated.

[YunchuWang]

Status update — client-side already resolved (#282); server-side fix now open as a PR

Client-side (durable-functions v4 / durabletask-js) — DONE in #282

The compat client already handles terminal/wrong-state control-plane ops with v3 parity. client.ts's _mapControlPlaneError (invoked from terminate / suspend / resume / raiseEvent) keys off the instance's ACTUAL runtime state via a getOrchestrationState round-trip and maps:

• TERMINAL (Completed/Failed/Terminated/Canceled) -> swallow, no-op (v3 410-Gone parity).
• non-terminal wrong-state -> throw Cannot <op> orchestration instance in the <State> state. (raiseEvent resurfaces the original error, matching v3).
• missing instance -> No instance with ID '<id>' found.
• transient state-lookup failure -> resurface the original gRPC error (never masked as not-found).

The 3 e2e specs this issue said were skipped in #282 are now un-skipped, real assertions: test/e2e-functions/terminate.spec.ts (terminate-of-terminated, terminate-of-completed) and suspend-resume.spec.ts (suspend/resume-of-completed).

Server-side (extension) — the remaining gap, now fixed in a PR

Root cause of the opaque 2 UNKNOWN is in azure-functions-durable-extension src/WebJobs.Extensions.DurableTask/TaskHubGrpcServer.cs: TerminateInstance and RaiseEvent already wrap their body in try/catch and map InvalidOperationException -> FailedPrecondition (with detail) and ArgumentException -> NotFound, but SuspendInstance and ResumeInstance had no try/catch at all, so the InvalidOperationException thrown by DurableClient.SuspendAsync/ResumeAsync (Cannot suspend/resume the orchestration instance {id} because instance is in the {State} state.) bubbled to the gRPC default handler and surfaced as StatusCode.Unknown (2 UNKNOWN: Exception was thrown by handler).

Fix: Azure/azure-functions-durable-extension#3478 wraps SuspendInstance / ResumeInstance with the same try/catch as TerminateInstance, so wrong-state suspend/resume now return 9 FAILED_PRECONDITION with the Cannot suspend/resume ... in the <State> state. detail instead of opaque 2 UNKNOWN. This benefits all language SDKs (JS, Python, Java, .NET-isolated), not just v4. The extension build check is green.

Once #3478 (server-side) merges, the client's suspend/resume path could optionally be simplified to trust the server's FAILED_PRECONDITION detail instead of the extra getOrchestrationState round-trip, but that's a follow-up optimization — behavior is already correct today.

Keeping this issue open until the server-side PR (#3478) merges.

[YunchuWang]

Resolved — both halves merged

The server-side fix Azure/azure-functions-durable-extension#3478 merged to dev (squash fe4fed22, 2026-07-23). Both halves of this issue are now complete:

• Client-side (durable-functions v4 / durabletask-js) — done in Add durable-functions@4.0.0 — Azure Functions Durable provider on the gRPC core (+ core host helpers, E2E CI, and release pipeline) #282 (merged 2026-07-22). client.ts's _mapControlPlaneError gives v3 parity for the terminal case (swallow / no-op), the non-terminal wrong-state case (Cannot <op> orchestration instance in the <State> state.), and the missing-instance case (No instance with ID '<id>' found.). The 3 previously-skipped e2e specs (terminate.spec.ts terminate-of-terminated / terminate-of-completed, and suspend-resume.spec.ts suspend/resume-of-completed) are un-skipped with real assertions.
• Server-side (extension) — done in #3478. SuspendInstance / ResumeInstance now map wrong-state InvalidOperationException → 9 FAILED_PRECONDITION (with the Cannot suspend/resume ... in the <State> state. detail) and missing-instance ArgumentException → 5 NOT_FOUND, instead of the opaque 2 UNKNOWN: Exception was thrown by handler. This benefits all language SDKs (JS, Python, Java, .NET-isolated), not just v4. e2e coverage: the extension's SuspendResumeTests now assert the FAILED_PRECONDITION mapping, plus new not-found suspend/resume tests mirroring TerminateNonExistant.

Closing as resolved.

Optional follow-up (not blocking): now that the server returns a meaningful FAILED_PRECONDITION detail, the v4 compat client's suspend/resume path could drop the extra getOrchestrationState round-trip and trust the server status directly. Behavior is already correct today — this is purely an optimization and can be tracked separately if we want it.