anomalyco/sst · error · DescribeError

Failed to describe workflow

Error message

Failed to describe workflow

What it means

Thrown by the public `describe` function when the GET request to `/2025-12-01/durable-executions/{arn}` returns a non-OK HTTP status, or when the response body is missing required fields (DurableExecutionArn, DurableExecutionName, FunctionArn, StartTimestamp, Status). It wraps the raw Response so you can inspect status code and body. The library throws it because it cannot return a valid DescribeResponse from an error response or a malformed payload.

Source

Thrown at sdk/js/src/aws/workflow.ts:350

    };
  }

  /**
   * Get the details for a single workflow execution.
   */
  export async function describe(
    arn: string,
    options?: Options,
  ): Promise<DescribeResponse> {
    const response = await awsFetch(
      "lambda",
      `/2025-12-01/durable-executions/${encodeURIComponent(arn)}`,
      {
        method: "GET",
      },
      options,
    );
    if (!response.ok) throw new DescribeError(response);

    const data = (await response.json()) as Partial<DescribeInvocationResponse>;

    if (
      !data.DurableExecutionArn ||
      !data.DurableExecutionName ||
      !data.FunctionArn ||
      data.StartTimestamp === undefined ||
      data.Status === undefined
    ) {
      throw new DescribeError(response);
    }

    const execution = parseExecution(data as DescribeInvocationResponse);
    return {
      ...execution,
      version: data.Version,
    };

View on GitHub (pinned to a0bd20f762)

Solutions

1. Check the HTTP status on the thrown error (it wraps the Response) — 404 means the ARN does not exist; verify the ARN and region.
2. Confirm IAM credentials include lambda:GetDurableExecution for the target function/execution.
3. Retry on 429/5xx with exponential backoff (or pass retry options via the Options parameter).
4. If status is 200 but fields are missing, upgrade the SDK — the API response shape likely changed (e.g. newer API version than this SDK's 2025-12-01 path).

Example fix

// before
const wf = await describe(arnFromLog); // throws DescribeError 404
// after
const arn = arnFromLog.trim();
const wf = await describe(arn, { region: "us-east-1" }).catch((err) => {
  if (err instanceof DescribeError && err.response.status === 404) return null;
  throw err;
});
if (!wf) console.warn("execution not found:", arn);

import { Arn } from "@aws-sdk/util-arn-parser";
function isDurableExecutionArn(arn: string): boolean {
  try {
    const p = Arn.parse(arn);
    return p.service === "lambda" && arn.includes("durable-executions") || /^arn:aws[a-z-]*:lambda:/.test(arn);
  } catch { return false; }
}
if (!isDurableExecutionArn(arn)) throw new Error(`invalid execution ARN: ${arn}`);

function isDescribeError(err: unknown): err is DescribeError {
  return err instanceof DescribeError && typeof err.response?.status === "number";
}

try {
  const wf = await describe(arn);
} catch (err) {
  if (err instanceof DescribeError) {
    if (err.response.status === 404) return null; // not found
    if (err.response.status === 403) throw new Error("missing lambda:GetDurableExecution permission");
    if (err.response.status === 429 || err.response.status >= 500) return retryWithBackoff(() => describe(arn));
  }
  throw err;
}

When it happens

Trigger: Calling `Workflow.describe(arn)` where: (1) the ARN does not exist (404, e.g. typo or wrong region/execution already deleted); (2) credentials lack `lambda:GetDurableExecution` (403); (3) throttling or transient 5xx from Lambda; (4) the API returns 200 but a body missing one of the required fields.

Common situations: Describing an execution whose retention expired so it was deleted; using an ARN from another region or account; assuming a role without the durable-executions describe permission; querying immediately after a deploy changed the function; typos when copying an ARN from logs.

Related errors

• Failed to stop workflow
• Failed to succeed workflow callback
• Failed to fail workflow callback
• You must provide a KMS key via `kmsKey` when configuring `cu
• Cannot set both "logging.retention" and "logging.logGroup"

AI-assisted analysis of anomalyco/sst@a0bd20f762 (2026-08-30). Data as JSON: /api/errors/2b649d209a1daf8b. Report an issue: GitHub.