{"record":{"id":"1bc644462eef27a6","repo":"anomalyco/sst","slug":"failed-to-describe-task","errorCode":null,"errorMessage":"Failed to describe task","messagePattern":"Failed to describe task","errorType":"error_code","errorClass":"DescribeError","httpStatus":null,"severity":"error","filePath":"sdk/js/src/aws/task.ts","lineNumber":166,"sourceCode":"   * [`DescribeTasks`](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html).\n   */\n  export async function describe(\n    resource: Resource,\n    task: string,\n    options?: Options\n  ): Promise<DescribeResponse> {\n    const res = await awsFetch(\"ecs\", \"/\", {\n      method: \"POST\",\n      headers: {\n        \"X-Amz-Target\": \"AmazonEC2ContainerServiceV20141113.DescribeTasks\",\n        \"Content-Type\": \"application/x-amz-json-1.1\",\n      },\n      body: JSON.stringify({\n        cluster: resource.cluster,\n        tasks: [task],\n      }),\n    }, options);\n    if (!res.ok) throw new DescribeError(res);\n\n    const data = (await res.json()) as {\n      tasks?: {\n        taskArn: string;\n        lastStatus: string;\n      }[];\n    };\n    if (!data.tasks?.length) throw new DescribeError(res);\n\n    return {\n      arn: data.tasks[0].taskArn,\n      status: data.tasks[0].lastStatus,\n      response: data,\n    };\n  }\n\n  /**\n   * Runs a task.","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/anomalyco/sst/blob/a0bd20f762883e72a35caccb4896c42ce5b3f707/sdk/js/src/aws/task.ts#L148-L184","documentation":"`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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read `error.response` body for the exact AWS error code to identify the root cause.","Ensure the calling function's IAM role has `ecs:DescribeTasks` on the cluster.","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).","Verify the cluster resource is linked and deployed in the current stage."],"exampleFix":"try {\n  const t = await task.describe(Resource.MyTask, arn);\n} catch (e) {\n  if (e instanceof task.DescribeError) {\n    console.error(await e.response.text());\n  }\n}","handlingStrategy":"try-catch","validationCode":"if (!arn.startsWith(\"arn:aws:ecs:\")) {\n  throw new Error(`Invalid ECS task ARN: ${arn}`);\n}","typeGuard":"function isDescribeError(e: unknown): e is task.DescribeError {\n  return e instanceof task.DescribeError && typeof e.response === \"object\";\n}","tryCatchPattern":"try {\n  const t = await task.describe(Resource.MyTask, arn);\n} catch (e) {\n  if (isDescribeError(e)) {\n    const awsError = await e.response.text();\n    if (e.response.status === 400) console.error(\"Bad request / bad ARN:\", awsError);\n    if (e.response.status === 403) console.error(\"Missing ecs:DescribeTasks permission\");\n  }\n  throw e;\n}","preventionTips":["Link the task/cluster resource to functions that describe tasks so IAM is configured.","Store and pass full, untruncated task ARNs (enable long ARN format account-wide).","Validate ARN format before calling describe."],"tags":["aws","ecs","network","iam"],"backgroundTag":"aws-api-request-failed","analyzedSha":"a0bd20f762883e72a35caccb4896c42ce5b3f707","analyzedAt":"2026-08-30T11:26:00.383Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}