{"record":{"id":"b7ba25d7f877a73b","repo":"anomalyco/sst","slug":"failed-to-run-task","errorCode":null,"errorMessage":"Failed to run task","messagePattern":"Failed to run task","errorType":"error_code","errorClass":"RunError","httpStatus":null,"severity":"error","filePath":"sdk/js/src/aws/task.ts","lineNumber":266,"sourceCode":"        },\n        overrides: {\n          ...(options?.cpu ? { cpu: (parseFloat(options.cpu.replace(\" vCPU\", \"\")) * 1024).toString() } : {}),\n          ...(options?.memory ? { memory: (parseFloat(options.memory.replace(\" GB\", \"\")) * 1024).toString() } : {}),\n          ...(options?.storage ? { ephemeralStorage: { sizeInGiB: parseInt(options.storage.replace(\" GB\", \"\")) } } : {}),\n\n          containerOverrides: resource.containers.map((name) => ({\n            name,\n            environment: Object.entries(environment ?? {}).map(\n              ([key, value]) => ({\n                name: key,\n                value,\n              })\n            ),\n          })),\n        },\n      }),\n    }, options);\n    if (!res.ok) throw new RunError(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 RunError(res);\n\n    return {\n      arn: data.tasks[0].taskArn,\n      status: data.tasks[0].lastStatus,\n      response: data,\n    };\n  }\n\n  /**\n   * Stops a task.","sourceCodeStart":248,"sourceCodeEnd":284,"githubUrl":"https://github.com/anomalyco/sst/blob/a0bd20f762883e72a35caccb4896c42ce5b3f707/sdk/js/src/aws/task.ts#L248-L284","documentation":"`task.run` calls the ECS RunTask API via awsFetch. If the HTTP response is not OK, a `RunError` with message \"Failed to run task\" is thrown, with the raw `Response` attached as `error.response` for reading the AWS error detail (e.g. AccessDeniedException, No cluster found).","triggerScenarios":"Calling `task.run(resource, ...)` where the ECS RunTask request returns non-OK: missing IAM `ecs:RunTask` permission, cluster doesn't exist, invalid task definition family, missing `iam:PassRole` for the task role, or no capacity available.","commonSituations":"Function's IAM role lacks ecs:RunTask and iam:PassRole; task definition family renamed across deploys; Fargate cluster has no capacity in the AZ; environment variables referencing removed resources; launching before the first deploy finished creating the cluster.","solutions":["Read `error.response` body for the exact AWS error code.","Grant the caller's IAM role `ecs:RunTask` plus `iam:PassRole` on the task execution/role.","Verify the linked task resource's cluster and task definition exist in the current stage (redeploy if needed).","Check ECS capacity/launch type settings; retry with backoff on capacity-related throttling errors."],"exampleFix":"try {\n  const ret = await task.run(Resource.MyTask, { message: body });\n} catch (e) {\n  if (e instanceof task.RunError) {\n    console.error(await e.response.text());\n  }\n}","handlingStrategy":"retry","validationCode":"import { Resource } from \"sst\";\nif (!Resource.MyTask?.cluster) throw new Error(\"Task resource not linked to this function; add `link: [Resource.MyTask]`\");","typeGuard":"function isRunError(e: unknown): e is task.RunError {\n  return e instanceof task.RunError && typeof e.response === \"object\";\n}","tryCatchPattern":"for (let attempt = 0; attempt < 3; attempt++) {\n  try {\n    return await task.run(Resource.MyTask, input);\n  } catch (e) {\n    if (!isRunError(e) || e.response.status < 500) throw e;\n    await new Promise(r => setTimeout(r, 2 ** attempt * 200));\n  }\n}\nthrow new Error(\"RunTask failed after retries\");","preventionTips":["Link the task resource so the function gets ecs:RunTask and iam:PassRole permissions.","Read `e.response` body to distinguish permission vs capacity vs task-definition errors.","Redeploy after changing task definition or cluster config so bindings stay in sync."],"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"}