RCA: ForgeAgents - API_NOT_FOUND on Previous Revision Manifest

Overview#

What Happened#

2026-04-28 11:39:40 UTC에 cupixworks-any-bimrevision-agent 서비스(eu-central-1)에서 BIM revision 1728의 비교 작업 중 Autodesk Forge/APS Model Derivative API가 이전 revision의 manifest를 찾을 수 없다는 API_NOT_FOUND 에러를 반환했다. 이전 revision의 URN이 가리키는 Revit 파일(FS0732-STR-SW-XX-MM3-L-0001.rvt)은 약 4개월 전(2025-12) 업로드된 객체로, Forge에서 해당 manifest/derivative가 만료되었거나 OSS bucket에서 삭제된 것으로 추정된다. 동일 세션의 첫 번째 job(BIM revision 1727)은 정상 완료되었다.

Quick Facts#

Affected Teams#

Timeline#

1. 11:39:34 UTC — 세션 시작, 첫 번째 job (BIM revision 1727) 처리 시작
2. 11:39:38 UTC — 첫 번째 job 정상 완료, 두 번째 job (BIM revision 1728) 처리 시작
3. 11:39:39 UTC — runBimCompare 시작, current URN (ts 1777375666743)과 previous URN (ts 1765992408129) 비교 요청
4. 11:39:40.689 UTC — Forge API가 previous URN manifest에 대해 API_NOT_FOUND 반환
5. 11:39:40.691 UTC — ForgeErrorMapper가 API_NOT_FOUND를 unmapped error로 감지, REV1 (UNKNOWN)으로 매핑
6. 11:39:41 UTC — 작업 정리 후 SQS 메시지 삭제 (재시도 불가)

Error Log#

Datadog Logs

ForgeAgents - Error: { code: API_NOT_FOUND, message: Resource not found: manifest/dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6dGVzbGEtZW1lYV9ldS1jZW50cmFsLTEtcHJvZHVjdGlvbi8xMDUyXzE3NjU5OTI0MDgxMjlfRlMwNzMyLVNUUi1TVy1YWC1NTTMtTC0wMDAxLnJ2dA== }

Impact#

• Service: cupixworks-any-bimrevision-agent
• 발생 횟수: 1
• 최초 발생: 2026-04-28T11:39:40.689Z
• 최근 발생: 2026-04-28T11:39:40.689Z

BIM revision 1728의 비교가 실패하여 bim_comparison_state가 Error로 설정되었다. SQS 메시지가 삭제되었으므로 자동 재시도는 발생하지 않는다. 사용자 tom.marsh@bouygues-uk.com(team byuk)의 BIM revision 비교 결과를 확인할 수 없는 상태이다.

Root Cause Summary#

Autodesk Forge/APS Model Derivative API가 이전 BIM revision(1278)의 manifest를 찾을 수 없어 API_NOT_FOUND 에러를 반환했다. Base64 디코딩 결과 해당 URN은 urn:adsk.objects:os.object:tesla-emea_eu-central-1-production/1052_1765992408129_FS0732-STR-SW-XX-MM3-L-0001.rvt로, 파일명의 timestamp(1765992408129)로부터 약 4개월 전(2025-12-17) 업로드된 객체임을 확인할 수 있다. Forge Model Derivative 서비스는 일정 기간 미사용 시 manifest/derivative를 자동 정리(evict)하거나, 원본 OSS 객체가 삭제된 경우 manifest 조회가 실패한다. 에이전트 코드에는 이 시나리오에 대한 별도 처리가 없으며, ForgeErrorMapper에도 API_NOT_FOUND 코드가 매핑되어 있지 않아 UNKNOWN(REV1)으로 fallback 처리된다.

Technical Analysis#

Code Path#

1. Entry point: bim-revision-service.ts:150 — run() 메서드가 SQS 메시지에서 targetId(1728)와 previousTargetId(1278)를 추출하여 처리 시작

2. BIM revision 로드: bim-revision-service.ts:166-167 — loadBimRevision(1728), loadPreviousBimRevision(1278) 호출하여 Tesla API에서 두 revision의 Forge URN 포함 메타데이터를 가져옴

3. Forge 인증 및 비교 실행: bim-revision-service.ts:174-177 — Forge region 설정(EMEA), 인증 후 runBimCompare() 호출

private runBimCompare = async (cpBimRevision: CPBimRevision, cpPreviousBimRevision: CPBimRevision): Promise<void> => {
	logger.info('BimRevisionService::runBimCompare | begin');
	if (cpBimRevision.forgeUrn == undefined) throw new Error('forgeUrn of cpBimRevision is undefined');
	if (cpBimRevision.forgeFormatType == undefined) throw new Error('forgeFormatType of cpBimRevision is undefined');
	if (cpBimRevision.forgeRegion == undefined) throw new Error('forgeRegion of cpBimRevision is undefined');
	if (cpBimRevision.cpBim == undefined) throw new Error('cpBim of cpBimRevision is undefined');
	if (cpPreviousBimRevision.forgeUrn == undefined) throw new Error('forgeUrn of cpPreviousBimRevision is undefined');
	if (cpPreviousBimRevision.forgeFormatType == undefined) throw new Error('forgeFormatType of cpPreviousBimRevision is undefined');
	if (cpPreviousBimRevision.forgeRegion == undefined) throw new Error('forgeRegion of cpPreviousBimRevision is undefined');

4. 비교 파라미터 구성: bim-revision-service.ts:617-638 — previousUrn으로 이전 revision의 Forge URN이 전달됨

5. Child process 실행: bim-compare.manager.ts:53-67 → bim-compare.process.ts:72-81 — ForgeAgent.extract()가 extractCompare.urn(previousUrn)의 manifest를 조회할 때 Forge API가 API_NOT_FOUND 반환

const result: ForgeAgent.Result = await ForgeAgent.extract(params.apiConfig, params.urn, {
	region: params.region,
	extractRoom: false,
	extractMeta: false,
	extractCompare: {
		urn: params.previousUrn,
		region: params.previousRegion,
		query: params.query
	}
});

6. 에러 처리 (Failure point): bim-revision-service.ts:657-671 — forgeErrorCode가 API_NOT_FOUND(string)로 설정됨. ForgeErrorMapper.isIgnorableError()는 false 반환(ignorable 목록에 없음). mapForgeErrorToRevisionError()에서 API_NOT_FOUND가 ForgeAgentErrorCode enum 값에 포함되지 않아 UNKNOWN(REV1)으로 매핑.

static mapForgeErrorToRevisionError(forgeErrorCode: ForgeAgentErrorCode | any): string {
	if (Object.values(ForgeAgentErrorCode).includes(forgeErrorCode)) {
		return ErrorCode.Revision.statusCode(forgeErrorCode);
	}
	logger.warn('ForgeErrorMapper::mapForgeErrorToRevisionError | Unmapped forge error code detected - forgeErrorCode: %s, type: %s, mapping to UNKNOWN (REV1)', forgeErrorCode, typeof forgeErrorCode);
	return ErrorCode.Revision.statusCode(ForgeAgentErrorCode.UNKNOWN);
}

7. 에러 전파: bim-revision-service.ts:668-670 — setErrorCode(REV1) 설정 후 throw. run() catch 블록(bim-revision-service.ts:188-191)에서 bim_comparison_state를 Error로 업데이트

} catch (ec: any) {
	logger.error('BimRevisionService::run | error: %s', JSON.stringify(ec.message));
	await this.updateBimRevisionBimComparisonState(targetId, TESLA.UpdateBimRevisionRequest.BimComparisonStateEnum.Error, this.errorCode);
}

Log Evidence#

Datadog 검색 쿼리:

service:cupixworks-any-bimrevision-agent status:error @environment:production

service:cupixworks-any-bimrevision-agent @environment:production

전체 세션(f5200b37a969198c)의 주요 로그 흐름:

Job 2 시작 — BIM Revision 1728 비교 파라미터 (11:39:39 UTC):

BimRevisionService::runBimCompare | params - urn: [current_urn], formatType: svf2, region: EMEA, previousUrn: [previous_urn with ts 1765992408129], previousFormatType: svf2, previousRegion: EMEA

Forge API 에러 (11:39:40.689 UTC):

ForgeAgents - Error: { code: API_NOT_FOUND, message: Resource not found: manifest/dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6dGVzbGEtZW1lYV9ldS1jZW50cmFsLTEtcHJvZHVjdGlvbi8xMDUyXzE3NjU5OTI0MDgxMjlfRlMwNzMyLVNUUi1TVy1YWC1NTTMtTC0wMDAxLnJ2dA== }

에러 매핑 경고 (11:39:40.690 UTC):

ForgeErrorMapper::mapForgeErrorToRevisionError | Unmapped forge error code detected - forgeErrorCode: API_NOT_FOUND, type: string, mapping to UNKNOWN (REV1)

Critical 에러 판정 (11:39:40.691 UTC):

BimRevisionService::runBimCompare | Critical Forge error detected - forgeErrorCode: API_NOT_FOUND, mapped to revisionErrorCode: REV1

Base64 디코딩 결과:

urn:adsk.objects:os.object:tesla-emea_eu-central-1-production/1052_1765992408129_FS0732-STR-SW-XX-MM3-L-0001.rvt

timestamp 1765992408129는 2025-12-17 경으로, 현재 시점(2026-04-28)에서 약 4개월 이전 업로드된 파일이다. Autodesk Forge Model Derivative API는 비활성 derivative를 일정 기간 후 자동 정리한다.

Hypotheses Considered#

Fix Recommendation#

즉시 조치 (Critical)#

• 없음. 단건 발생이며 외부 API(Autodesk Forge)의 데이터 가용성 문제로, 코드 수정만으로 해결할 수 없다. BIM revision 1728에 대해 수동으로 Forge re-translation을 트리거하거나, 사용자에게 이전 revision의 Forge derivative가 만료되었음을 안내할 필요가 있다.

단기 개선 (1주 이내)#

• ForgeErrorMapper에 API_NOT_FOUND 매핑 추가 (forge-error-mapper.ts:20-21): API_NOT_FOUND를 ForgeAgentErrorCode enum에 추가하거나, 별도의 매핑 로직을 구성하여 명시적인 에러 코드(예: REV_MANIFEST_NOT_FOUND)로 변환. 현재 UNKNOWN(REV1)으로 매핑되면 운영팀이 원인을 추적하기 어렵다.
• 에러 메시지에 previous URN 디코딩 정보 포함: runBimCompare 에러 로그에 이전 revision의 URN을 디코딩하여 bucket/object key를 명시하면 디버깅이 용이해진다.

장기 개선 (재발 방지)#

• Manifest 사전 검증: runBimCompare 실행 전에 previous URN의 manifest 존재 여부를 Forge API로 사전 조회(GET /modelderivative/v2/designdata/{urn}/manifest)하여, 없는 경우 사용자에게 re-translation을 안내하거나 자동 재변환 트리거.
• Forge derivative 수명 모니터링: 오래된 BIM revision의 Forge derivative가 만료되기 전에 갱신하거나, 만료 시 사용자에게 알림을 제공하는 프로세스 구축.
• SQS 메시지 삭제 정책 검토: 현재 에러 발생 후에도 SQS 메시지가 즉시 삭제되어 재시도가 불가능하다. 특정 에러 유형(외부 API 일시적 문제)에 대해서는 visibility timeout 기반 재시도를 고려할 수 있다.

Monitoring#

• API_NOT_FOUND 에러 발생 빈도 추적:

service:cupixworks-any-bimrevision-agent status:error "API_NOT_FOUND" @environment:production

• Unmapped forge error code 경고 모니터링:

service:cupixworks-any-bimrevision-agent "Unmapped forge error code" @environment:production

• 이전 revision manifest 조회 실패율 메트릭 추가 (Forge API response code별 카운트)

Risk Assessment#

• Risk level: low
• 예상 복잡도: standard
• 단건 발생이며 특정 사용자의 오래된 BIM revision에 한정된 문제. 시스템 전반에 영향을 미치지 않으며, 다른 BIM revision 비교 작업은 정상 동작 중. 다만 오래된 revision과 비교하는 케이스가 늘어날 경우 유사 에러가 반복될 수 있으므로, ForgeErrorMapper 매핑 추가와 manifest 사전 검증을 권장한다.