anomalyco/sst · error · DescribeError

Failed to describe task

Error message

Failed to describe task

What it means

`task.describe` calls the ECS DescribeTask API via awsFetch. If the HTTP response is not OK, a `DescribeError` with message "Failed to describe task" is thrown; the raw `Response` is attached as `error.response` so you can read the AWS error body (e.g. AccessDeniedException, ClusterNotFoundException).

Source

Thrown at sdk/js/src/aws/task.ts:166

   * [`DescribeTasks`](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html).
   */
  export async function describe(
    resource: Resource,
    task: string,
    options?: Options
  ): Promise<DescribeResponse> {
    const res = await awsFetch("ecs", "/", {
      method: "POST",
      headers: {
        "X-Amz-Target": "AmazonEC2ContainerServiceV20141113.DescribeTasks",
        "Content-Type": "application/x-amz-json-1.1",
      },
      body: JSON.stringify({
        cluster: resource.cluster,
        tasks: [task],
      }),
    }, options);
    if (!res.ok) throw new DescribeError(res);

    const data = (await res.json()) as {
      tasks?: {
        taskArn: string;
        lastStatus: string;
      }[];
    };
    if (!data.tasks?.length) throw new DescribeError(res);

    return {
      arn: data.tasks[0].taskArn,
      status: data.tasks[0].lastStatus,
      response: data,
    };
  }

  /**
   * Runs a task.

View on GitHub (pinned to a0bd20f762)

Solutions

1. Read `error.response` body for the exact AWS error code to identify the root cause.
2. Ensure the calling function's IAM role has `ecs:DescribeTasks` on the cluster.
3. Confirm the task ARN belongs to `resource.cluster` and the same region (ECS ARNs can be truncated to 255 chars by some services — use the full ARN).
4. Verify the cluster resource is linked and deployed in the current stage.

Example fix

try {
  const t = await task.describe(Resource.MyTask, arn);
} catch (e) {
  if (e instanceof task.DescribeError) {
    console.error(await e.response.text());
  }
}

if (!arn.startsWith("arn:aws:ecs:")) {
  throw new Error(`Invalid ECS task ARN: ${arn}`);
}

function isDescribeError(e: unknown): e is task.DescribeError {
  return e instanceof task.DescribeError && typeof e.response === "object";
}

try {
  const t = await task.describe(Resource.MyTask, arn);
} catch (e) {
  if (isDescribeError(e)) {
    const awsError = await e.response.text();
    if (e.response.status === 400) console.error("Bad request / bad ARN:", awsError);
    if (e.response.status === 403) console.error("Missing ecs:DescribeTasks permission");
  }
  throw e;
}

When it happens

Trigger: Calling `task.describe(resource, taskArn)` where the ECS DescribeTasks request returns a non-OK status: missing IAM `ecs:DescribeTasks` permission, invalid cluster ARN, malformed task ARN, or region mismatch.

Common situations: Function's IAM role lacks ecs:DescribeTasks; task ARN from a different cluster or region than `resource.cluster`; using an ARN that was truncated/mangled (e.g. by a message queue truncation); querying after the cluster was deleted.

Related errors

• Failed to run task
• Failed to stop task
• Failed to publish event to bus
• There have been some minor changes to the "Cluster" componen
• You cannot provide both "vpc.containerSubnets" and "vpc.serv

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