RCA: CPBim::downloadOriginal | 404 - undefined path segment in Forge API URL

Overview#

What Happened#

2026-05-07T03:23:00Z에 cupixworks-any-thumbnail-agent 서비스(ap-southeast-2 리전)에서 BIM 모델의 썸네일 다운로드 시 Autodesk Forge API 호출이 404로 실패했다. URL 경로에 API 버전 prefix 대신 문자열 "undefined"가 포함되어 잘못된 endpoint로 요청이 전송되었다. 동일 fingerprint의 기존 클러스터(929471ae)에서 30건 이상 반복 발생 중인 이슈이다.

Quick Facts#

Timeline#

1. 2026-05-07T03:23:00.579Z — CPBim::downloadOriginal 에러 발생 (SQS 메시지 2차 수신)
2. 2026-05-07T03:23:00.581Z — BaseService::handlingMessageErrors에서 에러 캐치 및 로깅
3. 2026-05-07 — error-sweeper 클러스터 생성, RCA 수행

Error Log#

Datadog Logs

CPBim::downloadOriginal | end - {"message":"Request failed with status code 404","name":"AxiosError","stack":"AxiosError: Request failed with status code 404
    at settle (/tmp/agent/node_modules/forge-apis/node_modules/axios/dist/node/axios.cjs:1983:12)
    at IncomingMessage.handleStreamEnd (/tmp/agent/node_modules/forge-apis/node_modules/axios/dist/node/axios.cjs:3085:11)
    ...
    "url":"https://developer.api.autodesk.com/undefined/designdata/dXJuOmFkc2sud2lwcHJvZGFuejpmcy5maWxlOnZmLnNwQUdnVFduUnR1M2RYbWJPRW9jZ2c_dmVyc2lvbj04/thumbnail","params":{"width":"400","height":"400"},"responseType":"arraybuffer"},"code":"ERR_BAD_REQUEST","status":404}

Impact#

• Service: cupixworks-any-thumbnail-agent
• 발생 횟수: 1 (이 클러스터), 30+ (동일 fingerprint 클러스터 929471ae 포함)
• 최초 발생: 2026-05-07T03:23:00.579Z
• 최근 발생: 2026-05-07T03:23:00.579Z
• 영향: ap-southeast-2(호주) 리전의 BIM 모델 썸네일 생성 실패. SQS 메시지 재시도(ApproximateReceiveCount=2)에도 동일 실패 반복.

Root Cause Summary#

forge-apis 라이브러리의 DerivativesApi 생성자에 첫 번째 인자로 JavaScript undefined를 전달하고 있다. 이 인자는 API endpoint prefix (정상값: modelderivative/v2)로 사용되는데, undefined가 문자열로 변환되어 URL 경로에 "/undefined/designdata/{urn}/thumbnail"이 생성된다. Autodesk API 서버는 해당 경로를 인식하지 못하고 404를 반환한다.

Technical Analysis#

Code Path#

• Entry point: thumbnail-service.ts:77 — supportModel.downloadOriginal() 호출
• cpbim.ts:45 — downloadOriginal 메서드 시작
• cpbim.ts:59-60 — DerivativesApi 생성 시 첫 번째 인자로 undefined 전달
• cpbim.ts:68 — derivativesApi.getThumbnail() 호출
• Failure point: forge-apis/node_modules/axios/dist/node/axios.cjs:1983 — HTTP 404 응답 수신

실행 흐름:

1. SQS 메시지 수신 → ThumbnailService.run() → CPBim.downloadOriginal() 호출

const isContinue = await supportModel.setModel();
if (isContinue) {
    await supportModel.downloadOriginal();

2. downloadOriginal에서 DerivativesApi를 생성할 때 첫 번째 인자에 undefined 전달:

const derivativesApi = new FORGE.DerivativesApi(
    undefined, forgeRegion
);

3. forge-apis 라이브러리 내부에서 이 인자를 URL path prefix로 사용. undefined가 문자열 "undefined"로 변환:

https://developer.api.autodesk.com/undefined/designdata/{urn}/thumbnail

기대 URL:

https://developer.api.autodesk.com/modelderivative/v2/designdata/{urn}/thumbnail

4. forge-api.ts:34-35에서도 동일 패턴을 사용하지만, 해당 코드는 translate/getManifest 호출에 사용된다. getThumbnail 메서드에서만 이 문제가 발생할 가능성이 있으며, 이는 라이브러리 내부 URL 구성 로직의 차이에 기인할 수 있다.

this._derivativesApi = new FORGE.DerivativesApi(
    undefined, this.region
);

Log Evidence#

사용한 Datadog 쿼리:

service:cupixworks-any-thumbnail-agent status:error @environment:production "CPBim::downloadOriginal"
Time range: 2026-05-07T02:23:00Z to 2026-05-07T04:23:00Z

핵심 로그 1 — 에러 발생 (03:23:00.579Z):

{
  "message": "CPBim::downloadOriginal | end - {\"message\":\"Request failed with status code 404\",\"name\":\"AxiosError\"}",
  "status": "error",
  "url": "https://developer.api.autodesk.com/undefined/designdata/dXJuOmFkc2sud2lwcHJvZGFuejpmcy5maWxlOnZmLnNwQUdnVFduUnR1M2RYbWJPRW9jZ2c_dmVyc2lvbj04/thumbnail",
  "http_status": 404
}

핵심 로그 2 — BaseService 에러 핸들링 (03:23:00.581Z):

{
  "message": "BaseService::handlingMessageErrors | Error and message object",
  "sqs_message_id": "5e51fba7-741a-4316-a134-a17087ee1004",
  "ApproximateReceiveCount": 2
}

SQS 메시지의 ApproximateReceiveCount=2로 볼 때 이 메시지는 이미 한 번 실패 후 재시도된 것이며, 재시도에서도 동일하게 실패했다. 이는 일시적 장애가 아닌 코드 결함임을 확인한다.

Hypotheses Considered#

Fix Recommendation#

즉시 조치 (Critical)#

• 파일: packages/cupix-tesla-thumbnail-agent/src/model/cpbim.ts:59-60
• DerivativesApi 생성자의 첫 번째 인자를 undefined 대신 올바른 apiClient 인스턴스 또는 null로 전달해야 한다.
• forge-apis 라이브러리의 DerivativesApi 생성자 시그니처를 확인하여, apiClient가 undefined일 때 기본 URL prefix를 올바르게 사용하도록 수정하거나, 명시적으로 올바른 API client를 전달해야 한다.
• 대안: getThumbnail 호출을 forge-apis 의존 없이 직접 Autodesk REST API를 호출하도록 변경 (https://developer.api.autodesk.com/modelderivative/v2/designdata/{urn}/thumbnail).

단기 개선 (1주 이내)#

• forge-api.ts의 ForgeApi 클래스에서 getThumbnail 메서드를 추가하고, CPBim에서 이를 재사용하도록 리팩토링. 현재 CPBim은 DerivativesApi를 직접 생성하는 반면, ForgeApi 클래스는 이미 올바르게 초기화된 인스턴스를 보유하고 있다.
• forge-apis 라이브러리 버전 업그레이드 검토 (0.9.12 → 최신). undefined 처리 방식이 개선되었을 수 있다.

장기 개선 (재발 방지)#

• Autodesk Forge API 호출을 단일 래퍼(ForgeApi 클래스)로 통합하여 각 agent에서 직접 DerivativesApi를 생성하지 않도록 한다.
• 에러 핸들링 개선: 404 응답 시 URL을 로그에 포함하여 빠른 디버깅 가능하도록 한다 (현재 error 전체를 JSON.stringify하므로 URL이 포함되긴 하지만 구조화되어 있지 않다).

Monitoring#

• 추가할 메트릭: Forge API 호출의 HTTP status code별 카운트
• Datadog 쿼리 예시:

service:cupixworks-any-thumbnail-agent status:error "Request failed with status code 404" "undefined/designdata"

• URL에 /undefined/가 포함된 요청이 발생하면 즉시 알림 발생하도록 모니터 설정

Risk Assessment#

• Risk level: medium
• 예상 복잡도: standard
• ap-southeast-2 리전의 BIM 썸네일 생성이 지속적으로 실패하고 있으며, SQS 재시도로도 해결 불가. 다만 썸네일은 핵심 기능이 아닌 보조 기능이므로 서비스 전체 장애는 아님.