RCA: PostprocessorService::run - found skat-master error code - AGT5002

Overview#

What Happened#

2026-04-27 01:02:41 UTC에 cupixworks-capture-postprocessor-agent 서비스의 ap-southeast-2 리전에서 job 181610 처리 중 skat-master 결과 파일에 error code AGT5002(Scenemapper Execute 실패)가 포함되어 postprocessor agent가 에러를 발생시켰다. 이는 upstream skat-master 처리 단계에서 scenemapper 실행이 실패한 것을 postprocessor가 감지한 것이다.

Quick Facts#

Timeline#

1. 2026-04-27T01:02:40Z — BaseService::runByMessage job 181610 처리 시작, SQS 메시지 수신 (ap-southeast-2 큐)
2. 2026-04-27T01:02:41Z — CPCapture::fromSkatMasterResults — skat-master 결과 파일에서 error_code: "AGT5002" 감지
3. 2026-04-27T01:02:41Z — PostprocessorService::run — error code가 비어있지 않아 에러 throw
4. 2026-04-27T01:02:42Z — BaseService::handlingMessageErrors — "undefined response" 에러로 SQS 메시지 삭제 및 job error state 업데이트

Error Log#

Datadog Logs

PostprocessorService::run - found skat-master error code - AGT5002

Impact#

• Service: cupixworks-capture-postprocessor-agent
• Team: naylorlove
• 발생 횟수: 1
• 최초 발생: 2026-04-27T01:02:41.481Z
• 최근 발생: 2026-04-27T01:02:41.481Z

Root Cause Summary#

Skat-master(scenemapper) 처리 단계에서 capture의 3D alignment 실행(Execute)이 실패하여 결과 파일에 error code AGT5002가 기록되었다. Postprocessor agent는 loadSkatMasterResults에서 이 결과 파일을 읽고, CPCapture.fromSkatMasterResults로 error_code 필드를 파싱한 뒤, postprocessor-service.ts:92에서 errorCode !== '' 체크를 통해 에러를 감지하고 throw한다. 이는 postprocessor 자체의 버그가 아니라, upstream skat-master 처리의 실패를 정상적으로 전파하는 설계된 동작이다. 근본 원인은 skat-master의 scenemapper execute 단계 실패에 있다.

Technical Analysis#

Code Path#

• Entry point: base-service.ts:153 — runByMessage에서 SQS 메시지를 파싱하고 run(targetId, msgObject) 호출
• postprocessor-service.ts:64 — PostprocessorService.run에서 job 로드 후 capture 모델 생성
• postprocessor-service.ts:91 — fileSystemManager.loadSkatMasterResults(cpCapture) 호출
• file-system.manager.ts:178-203 — loadSkatMasterResults가 EFS의 skat-master 결과 JSON 파일을 읽고 cpCapture.fromSkatMasterResults(skatMasterResults) 호출
• cpcapture.ts:336-347 — fromSkatMasterResults가 결과에서 error_code 필드를 추출하여 this._errorCode에 저장
• Failure point: postprocessor-service.ts:92-96 — errorCode !== '' 조건이 참이면 에러 throw

await fileSystemManager.loadSkatMasterResults(cpCapture);
if (cpCapture.errorCode !== '') {
    this.jobManager.setErrorCode(cpCapture.errorCode);
    const msg = `PostprocessorService::run - found skat-master error code - ${cpCapture.errorCode}`;
    logger.error(msg);
    throw new Error(msg);
}

fromSkatMasterResults = (skatMasterResults: SkatMasterResults): boolean => {
    if (skatMasterResults == undefined) {
        logger.warn('CPCapture::fromSkatMasterResults | undefined result');
        return false;
    }
    logger.info('CPCapture::fromSkatMasterResults | %s', JSON.stringify(skatMasterResults));
    this._errorCode = skatMasterResults.error_code;
    this._currentTask = skatMasterResults.task_name;
    this._isPreviewAlignAvailable = skatMasterResults.is_preview_align_available;
    return true;
};

에러가 throw되면 base-service.ts:290의 handlingMessageErrors가 catch한다. 이 메서드에서 getApiErrorToDeleteMessage가 호출되는데, throw된 Error 객체에는 .response 프로퍼티가 없고 JSON 파싱도 불가하므로 response == undefined 분기를 타고 "undefined response"를 반환한다.

const response = CPUtils.isJsonString(error) ? JSON.parse(error) : error.response;
if (response == undefined) {
    logger.warn('BaseService::getApiErrorToDeleteMessage | undefined response', error);
    return 'undefined response';
}

이로 인해 SQS 메시지가 삭제되고 job 상태가 error로 업데이트된다.

AGT5002 코드 자체는 Scenemapper.Execute에 해당하며, skat-master가 scenemapper 실행 중 실패했음을 의미한다:

export class Scenemapper {
    static readonly Default = 'AGT5000';
    static readonly Initialize = 'AGT5001';
    static readonly Execute = 'AGT5002';
    static readonly Validate = 'AGT5003';
    static readonly AvailableReconstruction = 'AGT5004';

Log Evidence#

사용한 Datadog 쿼리:

service:cupixworks-capture-postprocessor-agent status:error "AGT5002"
Time range: 2026-04-27T00:02:41Z to 2026-04-27T01:32:41Z

service:cupixworks-capture-postprocessor-agent
Time range: 2026-04-27T01:00:00Z to 2026-04-27T01:05:00Z

전체 실행 플로우 (job 181610):

10:02:40 KST [info]  BaseService::runByMessage | id: 181610
10:02:40 KST [info]  CupixAuth::setSession | session_id: da1703d6...
10:02:40 KST [info]  JobManager::loadJob | begin - job id: 181610
10:02:40 KST [info]  JobManager::loadJob | end - job id: 181610
10:02:41 KST [info]  CPCapture::fromMeta | key: pWJ0SMocP, version: 1
10:02:41 KST [info]  CPCapture::fromSkatMasterResults | {"error_code":"AGT5002","skatsdk_version":{"ver":"0.0.8332-SM\t8312ddcec0413984f32a8514c91bcba297e32b6f\t20260316_091501\tarm64\tUbuntu 22.04.1 LTS"},"task_name":"preview","is_preview_align_available":true}
10:02:41 KST [warn]  PostprocessorService::run - found skat-master error code - AGT5002
10:02:41 KST [error] PostprocessorService::run - found skat-master error code - AGT5002
10:02:42 KST [error] BaseService::handlingMessageErrors | Error and message object - {"error":"undefined response","sqsMessage":{"MessageId":"d5d146ed-c283-4bf7-9631-c55b28752d27","Attributes":{"ApproximateReceiveCount":"1"}}}

핵심 로그 — skat-master 결과 파일의 내용:

{
  "error_code": "AGT5002",
  "skatsdk_version": {
    "ver": "0.0.8332-SM\t8312ddcec0413984f32a8514c91bcba297e32b6f\t20260316_091501\tarm64\tUbuntu 22.04.1 LTS"
  },
  "task_name": "preview",
  "is_preview_align_available": true
}

주목할 점:

• task_name이 "preview"이므로 preview alignment 작업 중 실패
• is_preview_align_available이 true이므로 preview align 자체는 가능했으나 execute 단계에서 실패
• SQS ApproximateReceiveCount가 "1"이므로 첫 번째 시도에서 실패
• 지난 7일간 동일 에러 패턴 1건만 발생 — 단발성 이벤트

Hypotheses Considered#

Fix Recommendation#

즉시 조치 (Critical)#

• 조치 불필요: 이 에러는 upstream skat-master의 scenemapper execute 실패를 postprocessor가 감지하여 정상 전파하는 설계된 동작이다. Postprocessor agent 코드에 버그가 없다.
• 실제 원인은 skat-master 서비스의 scenemapper execute 단계에 있으므로, skat-master 팀(처리 파이프라인 담당)에 해당 capture(key: pWJ0SMocP, job: 181610)의 실패 원인 조사를 요청해야 한다.

단기 개선 (1주 이내)#

• 에러 레벨 조정 검토: postprocessor-service.ts:95에서 upstream 에러 코드 전파 시 logger.error를 사용하고 있는데, 이는 upstream 처리 실패의 정상 감지이므로 logger.warn으로 변경하는 것을 검토할 수 있다. 다만, 현재 같은 줄에서 logger.warn도 함께 출력하고 있어 중복 로깅이 발생하고 있다(Datadog에서 같은 타임스탬프에 warn과 error 레벨 2건 확인).
• 에러 핸들링 개선: handlingMessageErrors에서 throw된 Error 객체의 .response가 없을 때 "undefined response"로 표시되는데, skat-master error code를 전파하는 경우 에러 메시지 자체를 보존하면 디버깅에 유리하다.

장기 개선 (재발 방지)#

• Skat-master 팀과 협력하여 AGT5002 (Scenemapper Execute) 실패의 근본 원인을 파악하고, scenemapper SDK 버전(0.0.8332-SM)의 안정성을 검증해야 한다.
• Skat-master 에러 코드별 자동 재시도 정책을 검토할 수 있다 (일부 transient한 execute 실패는 재처리로 복구 가능할 수 있음).

Monitoring#

• 기존 모니터링으로 충분하다. 단발성 이벤트이며, 동일 에러가 반복 발생 시 skat-master 서비스의 안정성 문제를 의심해야 한다.
• 추가 모니터링 고려:

service:cupixworks-capture-postprocessor-agent status:error "found skat-master error code"

위 쿼리로 skat-master 에러 코드별 발생 빈도를 추적할 수 있다.

Risk Assessment#

• Risk level: low
• 예상 복잡도: trivial — postprocessor 코드 수정 불필요, upstream skat-master 이슈