참고 자료
증상별 문제 해결
먼저 참가자 이름·계정·작업 폴더와 발생 시각을 확인합니다. 아래 명령은 05장에서 준비한 본인 app에서 실행합니다. 원본 운영 배포기나 다른 참가자의 설정으로 오류를 우회하지 않습니다.
set -euo pipefail
cd "$ROBOT_REPO"
python3 workshop/scripts/lab.py info --config "$ROBOT_CONFIG"
python3 workshop/scripts/lab.py doctor --config "$ROBOT_CONFIG" --aws
cd "$ROBOT_LAB"
test -f infra/workshop-binding.json
python3 -B scripts/deploy.py status
doctor --aws는 계정과 선택된 기존 자원 조회입니다. 실제 Bedrock 계획과 물리 실행을 검증하지 않습니다.
참가자 준비·빌드
| 증상 | 원인 구분 | 다음 조치 |
|---|---|---|
init 또는 prepare가 기존 파일 거부 |
기존 참가자 작업을 보호 | info로 소유권 확인 후 기존 app 사용 |
| 참가자 이름 거부 | 형식 또는 보호된 이름 | 진행자가 배정한 3–10자 소문자·숫자 이름 사용 |
| 계정 불일치 | 잘못된 프로파일/역할 | 처음 선택한 인증 경로 확인. 계정 바인딩을 수정하지 않음 |
| 로컬 포트 중복 | 다른 참가자의 포트 예약/프로세스 | 새 참가자 준비 시 init --api-port로 빈 연속 세 포트 선택 |
prepare-cloud 불가 |
도메인·인증서·네트워크 미완성 또는 기존 출력 | 05장 순서와 cloudPrepared 확인 |
| source adapter 변경 감지 | 원본 변경으로 검토된 생성기와 불일치 | 진행자가 생성기/소스 검증을 갱신. 가드 삭제 금지 |
| Node/Python 버전 오류 | 호스트 기본 실행 파일 사용 | 준비된 Node 24·Python 3.11 경로를 적용 |
| Docker 권한·ARM64 빌드 오류 | 준비된 빌드 환경/플랫폼 미확인 | 진행자와 Docker/빌드 지원 확인 |
| publish가 source/digest 거부 | 빌드 이후 코드나 이미지 변경 | 편집 완료 후 새 release로 build→publish→scan |
| 검증 도구 파일 없음 | 운영용 검증기는 사본에 포함되지 않음 | 자원 매핑의 참가자 .local/tools/ 코드 준비 |
이미 만들어진 app의 포트·계정·프로파일을 바꾸는 방법으로 다른 사용자의 충돌을 해결하지 않습니다. 로컬 작업과 클라우드 바인딩 변경이 필요하면 기존 상태를 보관하고 새 참가자 환경을 준비합니다.
CloudFormation·Fargate
cd "$ROBOT_LAB"
python3 -B scripts/deploy.py status --stack app
python3 .local/tools/verify-aws.py --skip-http
| 증상 | 확인할 항목 |
|---|---|
*_IN_PROGRESS |
AWS 작업이 진행 중. 같은 apply를 반복하지 않고 상태 조회 |
ROLLBACK_* 또는 CREATE_FAILED |
참가자 스택 Events에서 실패한 logical ID와 이유 |
| 소유 태그/stack ID 거부 | 다른 스택이거나 원격 상태 변경. 보호 검사를 유지 |
| Prefix List 규칙 생성 실패 | 정확한 AWS 관리형 목록과 SG 규칙 할당량. CIDR 전체 개방으로 우회하지 않음 |
Fargate CannotPullContainerError |
ECR digest/실행 역할·ARM64·NAT/endpoint |
ResourceInitializationError |
ECR/Secret/Logs 접근 경로, 실행 역할 |
target unhealthy |
웹 8098, /readyz, MuJoCo loopback 8099, 컨테이너 종료 이유 |
| 태스크가 반복 교체 | essential simulation 종료, 메모리·CPU·시작 지연, readiness |
| 앱은 배포됐지만 화면 없음 | 같은 release의 assets 게시 및 invalidation 여부 |
태스크 전체 환경이나 CloudFront 설정 JSON에는 비밀값이 들어갈 수 있습니다. 먼저 제공된 검증기의 제한된 출력을 사용합니다. 명령 예시의 “원본 헤더 확인”을 Secret 값 출력으로 구현하지 않습니다.
DNS·HTTPS·API
07장의 상태 출력에서 본인 공개 URL을 불러온 뒤 검사합니다.
python3 -B scripts/deploy.py status --stack app \
> .local/evidence/app-status.json
export ROBOT_URL="$(python3 -c 'import json; print(json.load(open(".local/evidence/app-status.json"))["outputs"]["PublicUrl"])')"
export ROBOT_DOMAIN="${ROBOT_URL#https://}"
dig +short CNAME "$ROBOT_DOMAIN"
curl --silent --show-error --max-time 30 \
--output /dev/null --write-out 'status=%{http_code}\ncontent-type=%{content_type}\n' \
"$ROBOT_URL/readyz"
python3 .local/tools/verify-aws.py
| 관찰 | 원인과 확인 순서 |
|---|---|
DNS 존에는 있지만 NXDOMAIN |
공개 NS 위임이 실제 관리 존을 가리키는지 확인 |
| 인증서 이름 오류 | viewer us-east-1, origin 서울, 두 인증서와 hostname 일치 |
| 정적 웹 정상·API 502 | ALB 기본 DNS, 전달 Host, origin TLS 체인/이름, ALB target |
| API 403 | WAF → ALB origin 검증 → Node Origin/CSRF/쿠키 순서로 구분 |
| API 504 | target 응답 시간, Runtime/모델, 시뮬레이터 제한 시간 |
/healthz 200·/readyz 503 |
Node만 살아 있고 MuJoCo는 준비되지 않은 상태 |
| 기본 CF 주소 308 | 본인 공개 hostname으로 이동하는 정상 동작 |
| 직접 ALB 호출 거부 | Prefix List·origin gate 보호가 정상일 수 있음 |
| 로그인 없이 새 창에서 run 404 | 해당 세션 소유 실행이 아님. ID 공유는 인증을 대신하지 않음 |
“서버 응답을 읽지 못했습니다. 연결을 확인해 주세요”만으로 원인을 확정하지 않습니다. 브라우저 Network에서 해당 요청의 status·Content-Type·경로·시각을 기록합니다. HTML 오류 응답을 API JSON으로 해석하려고 했는지 먼저 확인합니다. 쿠키나 CSRF 값이 포함된 HAR 전체를 그대로 공유하지 않습니다.
DNS 작업은 수동입니다. 잘못된 존을 해결하려고 루트 NS나 공유 레코드를 바꾸지 않습니다. 원본은 ALB 기본 DNS와 전달 Host를 사용하므로 별도 origin DNS를 생성해 우회하지 않습니다.
AgentCore·Bedrock
| 증상 | 확인 |
|---|---|
Runtime READY이나 요청 실패 |
READY와 실제 모델 호출은 별개. 06장의 호출 검사 실행 |
호출자 AccessDenied |
호출자의 본인 Runtime 접근 권한 |
bedrock_unavailable |
Runtime 실행 역할의 모델/추론 프로파일·SCP·리전 권한 |
planner_invalid_output / invalid_output |
실제 응답 계약·구조화 출력 지원·추가 필드·요청 범위 |
planner_timeout |
첫/반복 요청·모델 추론·네트워크·호출 제한 시간 구분 |
planner_throttled |
본인 모델/Runtime 할당량과 요청 빈도, 제한적 재시도 |
| Runtime 로그 그룹 없음 | 첫 실제 호출 여부, Runtime ID, 이후 configure-logs |
provider가 rules |
로컬 설정인지 확인. 실제 AI 연결 완료로 표시하지 않음 |
provider가 bedrock |
직접 호출 경로. AgentCore 배포 경로와 구별 |
계정에서 모델 목록이 보이는 것과 이 프로젝트의 Converse 구조화 출력 호출이 되는 것은 다릅니다. 모델 ID를 바꾸거나 오류 시 자동 fallback을 넣기 전에 진행자가 해당 조합을 검증해야 합니다.
실행·물리·취소
| 증상 | 확인과 기대 동작 |
|---|---|
429 simulation_busy |
글로벌 동시 물리 실행 1건. 끝난 뒤 재시도 |
429 session_busy |
같은 세션의 진행 중 작업 확인 |
| plan 404 | 다른 세션, plan 만료, 웹 프로세스 교체 여부 |
| replay 409 | 아직 진행 중이거나 취소된 실행 |
| failed + replay 존재 | 실제 물리 검사 실패. 실패 기록을 열어 원인 확인 |
| failed + replay 없음 | 시뮬레이터 통신·중단·저장 실패 확인 |
| 취소 후 즉시 재실행 불가 | 물리 요청 종료/제한 시간까지 용량 예약 유지 가능 |
| 손이 놓기 전 성공으로 보임 | 최종 release·support·stable 체크와 마지막 pose 확인 |
| 태스크 교체 뒤 오래 running | lease 만료 후 중단 실패 전이 확인. 성공으로 복구하지 않음 |
MAX_ACTIVE_RUNS를 키우거나 실패 판정을 제거하는 방식으로 해결하지 않습니다. 순서와 배치를 고정해 재현하고 tests/simulation의 실패 조건이 유지되는지 확인합니다.
조사 결과 기록
참가자 .local/evidence/에 시각·URL·release·명령·종료 코드·실패 체크·run ID·다음 조치만 남깁니다. 원인이 해결되면 해당 구간과 11장의 전체 경로를 필요한 범위에서 다시 검사합니다. 아직 해결하지 못한 항목은 미검증으로 남깁니다.