# Amazon ECS의 API 실패 이유
<a name="api_failures_messages"></a>

Amazon ECS API, 콘솔 또는 AWS CLI를 통해 트리거한 API 작업이 종료되고 `failures` 오류 메시지가 나타나면 다음을 통해 원인 해결에 도움을 줄 수 있습니다. 실패로 인해 실패와 연관된 리소스의 이유 및 Amazon 리소스 이름(ARN)이 반환됩니다.

대부분의 리소스는 리전 전용이므로 콘솔을 사용할 때에는 해당 리소스에 대한 올바른 리전을 설정했는지 확인해야 합니다. AWS CLI를 사용할 때에는 AWS CLI 명령이 `--region {{region}}` 파라미터가 포함된 올바른 리전으로 전송되고 있는지 확인합니다.

`Failure` 데이터 형식의 구조에 대한 자세한 내용은 *Amazon Elastic Container Service API 참조*의 [실패](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Failure.html)를 참조하세요.

다음은 API 명령을 실행할 때 수신할 수 있는 실패 메시지 예제입니다.



- ** `DescribeClusters` **
  - **실패 이유 또는 중단 사유:** `MISSING`
  - **원인:** 지정한 클러스터를 찾을 수 없습니다. 클러스터 이름의 맞춤법을 확인합니다.

- ** `DescribeInstances` **
  - **실패 이유 또는 중단 사유:** `MISSING`
  - **원인:** 지정한 컨테이너 인스턴스를 찾을 수 없습니다. 컨테이너 인스턴스가 등록된 클러스터를 지정했는지, 컨테이너 인스턴스 ARN 또는 ID가 모두 올바른지 확인합니다.

- ** `DescribeServices` **
  - **실패 이유 또는 중단 사유:** `MISSING`
  - **원인:** 지정한 서비스를 찾을 수 없습니다. 올바른 클러스터 또는 리전이 지정되었고 서비스 ARN 또는 이름이 유효한지 확인합니다.

- ** `DescribeTasks` **
  - **실패 이유 또는 중단 사유:** `MISSING`
  - **원인:** 지정한 태스크를 찾을 수 없습니다. 올바른 클러스터 또는 리전이 지정되었고 작업 ARN 또는 ID가 모두 유효한지 확인합니다.

- ** `DescribeTasks`  **
  - **실패 이유 또는 중단 사유:** `TaskFailedToStart: RESOURCE:*` / **원인:** `RESOURCE:CPU` 오류의 경우 작업에서 요청한 CPU 수를 컨테이너 인스턴스에서 사용할 수 없습니다. 이는 일반적으로 작업 정의의 CPU 단위 요구 사항이 용량 공급자에 매핑된 Auto Scaling 그룹에 정의된 Amazon EC2 인스턴스의 CPU 크기보다 클 때 발생합니다. 용량 공급자 구성을 확인해야 합니다.<br />`RESOURCE:MEMORY` 오류의 경우 작업에서 요청한 메모리 양을 컨테이너 인스턴스에서 사용할 수 없습니다. 이는 일반적으로 작업 정의의 메모리 크기 요구 사항이 용량 공급자에 매핑된 Auto Scaling 그룹에 정의된 Amazon EC2 인스턴스의 지원되는 메모리보다 클 때 발생합니다. 용량 공급자 구성을 확인해야 합니다.
  - **실패 이유 또는 중단 사유:** `TaskFailedToStart: AGENT` / **원인:** 태스크를 시작하려고 시도한 컨테이너 인스턴스에 현재 연결이 끊긴 에이전트가 있습니다. 작업 배치를 위한 대기 시간이 길어지는 것을 방지하기 위해 요청이 거부되었습니다.<br />연결이 끊어진 에이전트 문제 해결 방법에 대한 자세한 내용은 [연결이 끊어진 Amazon ECS 에이전트 문제를 해결하려면 어떻게 해야 하나요?](https://repost.aws/knowledge-center/ecs-agent-disconnected-linux2-ami)를 참조하세요.
  - **실패 이유 또는 중단 사유:** `TaskFailedToStart: MemberOf placement constraint unsatisfied` / **원인:** 작업 정의에 정의된 배치 제약 조건을 충족하는 컨테이너 인스턴스가 없습니다.
  - **실패 이유 또는 중단 사유:** `TaskFailedToStart: ATTRIBUTE` / **원인:** 태스크 정의에 컨테이너 인스턴스에서 사용할 수 없는 특정 컨테이너 인스턴스 속성을 필요로 하는 파라미터가 포함되어 있습니다. 예를 들어 해당 작업에서 `awsvpc` 네트워크 모드를 사용하지만 지정된 서브넷에 `ecs.capability.task-eni` 속성을 지닌 인스턴스가 없는 경우가 있습니다. 특정 태스크 정의 파라미터와 에이전트 구성 변수에 어떤 속성이 필요한지에 대한 자세한 내용은 [Fargate에 대한 Amazon ECS 태스크 정의 파라미터](task_definition_parameters.md) 및 [Amazon ECS 컨테이너 에이전트 구성](ecs-agent-config.md) 섹션을 참조하세요.
  - **실패 이유 또는 중단 사유:** TaskFailedToStart: NO ACTIVE INSTANCES / **원인:** 용량 공급자에 활성 인스턴스가 없습니다. Auto Scaling 그룹을 관리하는 방법에 대한 자세한 내용은 Amazon EC2 Auto Scaling 사용 설명서의 [Auto Scaling 그룹](https://docs.aws.amazon.com/autoscaling/ec2/userguide/auto-scaling-groups.html)을 참조하세요.
  - **실패 이유 또는 중단 사유:** `TaskFailedToStart: EMPTY CAPACITY PROVIDER` / **원인:** 클러스터에 인스턴스가 없습니다. 이는 대부분 용량 공급자가 비어 있거나 용량 공급자의 인스턴스가 클러스터에 등록되지 않았기 때문일 수 있습니다. Auto Scaling 그룹을 관리하는 방법에 대한 자세한 내용은 Amazon EC2 Auto Scaling 사용 설명서의 [Auto Scaling 그룹](https://docs.aws.amazon.com/autoscaling/ec2/userguide/auto-scaling-groups.html)을 참조하세요.

- ** `GetTaskProtection` **
  - **실패 이유 또는 중단 사유:** `MISSING` / **원인:** 지정한 태스크를 찾을 수 없습니다. 클러스터 이름 또는 ARN과 작업 ARN 또는 ID가 유효한지 확인합니다.
  - **실패 이유 또는 중단 사유:** `TASK_NOT_VALID` / **원인:** 지정된 작업은 Amazon ECS 서비스의 일부가 아닙니다. Amazon ECS 서비스 관리형 작업만 보호할 수 있습니다. 작업 ARN 또는 ID를 확인하고 다시 시도하세요.

- ** `RunTask` 또는 `StartTask` **
  - **실패 이유 또는 중단 사유:** `RESOURCE:*` / **원인:** 작업에서 요청한 리소스를 클러스터의 컨테이너 인스턴스에서 사용할 수 없습니다. 리소스가 CPU, 메모리, 포트 또는 탄력적 네트워크 인터페이스인 경우 클러스터에 추가 컨테이너 인스턴스를 추가해야 하는 경우도 있습니다.<br />`RESOURCE:ENI` 오류의 경우 클러스터에 사용 가능한 탄력적 네트워크 인터페이스 연결 지점이 없습니다. 이러한 연결 지점은 `awsvpc` 네트워크 모드를 사용하는 작업에 필요합니다. Amazon EC2 인스턴스에 연결할 수 있는 네트워크 인터페이스의 개수에는 한도가 있고 기본 네트워크 인터페이스는 한 개로 계산됩니다. 각 인스턴스 유형에 대해 지원되는 네트워크 인터페이스 수에 대한 자세한 내용은 *Amazon EC2 사용 설명서*의 [인스턴스 유형별 네트워크 인터페이스당 IP 주소](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html#AvailableIpPerENI)를 참조하세요.<br />`RESOURCE:GPU` 오류의 경우 작업에서 요청한 GPU 수를 사용할 수 없으며 GPU 지원 컨테이너 인스턴스를 클러스터에 추가해야 할 수 있습니다. 자세한 내용은 [GPU 워크로드에 대한 Amazon ECS 작업 정의](ecs-gpu.md) 섹션을 참조하세요.
  - **실패 이유 또는 중단 사유:** `AGENT` / **원인:** 태스크를 시작하려고 시도한 컨테이너 인스턴스에 현재 연결이 끊긴 에이전트가 있습니다. 작업 배치를 위한 대기 시간이 길어지는 것을 방지하기 위해 요청이 거부되었습니다.<br />연결이 끊어진 에이전트 문제 해결 방법에 대한 자세한 내용은 [연결이 끊어진 Amazon ECS 에이전트 문제를 해결하려면 어떻게 해야 하나요?](https://repost.aws/knowledge-center/ecs-agent-disconnected-linux2-ami)를 참조하세요.
  - **실패 이유 또는 중단 사유:** `LOCATION` / **원인:** 태스크를 시작하려고 시도한 컨테이너 인스턴스가 `awsVpcConfiguration`에서 지정한 서브넷과 다른 가용 영역에 있습니다.
  - **실패 이유 또는 중단 사유:** `ATTRIBUTE` / **원인:** 태스크 정의에 컨테이너 인스턴스에서 사용할 수 없는 특정 컨테이너 인스턴스 속성을 필요로 하는 파라미터가 포함되어 있습니다. 예를 들어 해당 작업에서 `awsvpc` 네트워크 모드를 사용하지만 지정된 서브넷에 `ecs.capability.task-eni` 속성을 지닌 인스턴스가 없는 경우가 있습니다. 특정 태스크 정의 파라미터와 에이전트 구성 변수에 어떤 속성이 필요한지에 대한 자세한 내용은 [Fargate에 대한 Amazon ECS 태스크 정의 파라미터](task_definition_parameters.md) 및 [Amazon ECS 컨테이너 에이전트 구성](ecs-agent-config.md) 섹션을 참조하세요.

- ** `StartTask` **
  - **실패 이유 또는 중단 사유:** `MISSING` / **원인:** 작업을 시작하려고 시도한 컨테이너 인스턴스를 찾을 수 없습니다. 잘못된 클러스터 또는 리전이 지정되었거나 컨테이너 인스턴스 ARN 또는 ID를 잘못 입력했는지 확인합니다.
  - **실패 이유 또는 중단 사유:** `INACTIVE` / **원인:** 태스크를 시작하려고 시도한 컨테이너 인스턴스가 이전에 Amazon ECS에 대한 등록이 취소되었고 사용할 수 없습니다.

- ** `StopServiceDeployment` **
  - **실패 이유 또는 중단 사유:** `ECS deployment failed`
  - **원인:** 사기 계정이 StopServiceDeployment API를 실행했습니다.

- ** `TagResource` **
  - **실패 이유 또는 중단 사유:** `InvalidParameterException`
  - **원인:** 태깅하려는 서비스의 ARN은 짧은 형식입니다. 긴 형식으로 마이그레이션해야 합니다. ARN 마이그레이션 방법에 대한 자세한 내용은 [Amazon ECS 단기 서비스 ARN을 긴 ARN으로 마이그레이션](service-arn-migration.md) 섹션을 참조하세요.

- ** `UpdateTaskProtection` **
  - **실패 이유 또는 중단 사유:** `DEPLOYMENT_BLOCKED` / **원인:** 하나 이상의 보호된 작업으로 인해 서비스 배포가 안정 상태에 도달하지 못하므로 작업 보호를 설정할 수 없습니다. 기존 작업에 대한 작업 보호를 해제하거나 작업 보호가 만료될 때까지 기다립니다.
  - **실패 이유 또는 중단 사유:** `MISSING` / **원인:** 지정한 태스크를 찾을 수 없습니다. 클러스터 이름 또는 ARN과 작업 ARN 또는 ID가 유효한지 확인합니다.
  - **실패 이유 또는 중단 사유:** `TASK_NOT_VALID` / **원인:** 지정된 작업은 Amazon ECS 서비스의 일부가 아닙니다. Amazon ECS 서비스 관리형 작업만 보호할 수 있습니다. 작업 ARN 또는 ID를 확인하고 다시 시도하세요.



**참고**  
여기에 설명된 실패 시나리오 외에도 API 작업은 예외로 인해 실패하여 오류 응답이 발생할 수도 있습니다. 이러한 예외 목록은 [일반 오류](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/CommonErrors.html)를 참조하세요.