RCA: Failed to get rooms from svf2

Overview#

What Happened#

cupixworks-any-room-agent 서비스에서 BIM 모델(id: 17157)의 SVF2 포맷 room extraction 중 Autodesk Forge Property Database 조회 실패로 에러가 발생했다. Forge API가 잘못된 object ID(범위 초과)를 접근하려 하면서 property 조회가 실패하고, 이것이 room extraction 전체 실패로 전파되었다.

Quick Facts#

Affected Teams#

Timeline#

1. 2026-05-17T23:56:16Z — 최초 발생 (14일 retention 범위 내, bim=3398, naylorlove)
2. 2026-05-27T09:23:06Z — 금일 발생 (bim=17157, exyte) - 이 클러스터에 감지됨
3. 2026-05-27T09:23:06Z — RCA 시작

Error Log#

Datadog Logs

Failed to get rooms from svf2

Impact#

• Service: cupixworks-any-room-agent
• Team: exyte
• 발생 횟수: 1 (이 클러스터), 16건 (최근 14일 전체)
• 최초 발생: 2026-05-27T09:23:06.436Z
• 최근 발생: 2026-05-27T09:23:06.436Z

Root Cause Summary#

Autodesk Forge Property Database에서 SVF2 모델의 node traversal 시 잘못된 object ID(유효 범위 1~19034503을 초과하는 19034504)에 접근하여 Failed to get properties and children 에러가 발생했다. @cupix/forge-agents 라이브러리의 extract() 함수가 이 에러를 result.Error 코드(code: 1)로 반환하는데, RoomExtractorProcess의 에러 핸들링 로직에서 FORGE_SOURCE_INVALID_MANIFEST가 아닌 모든 에러를 generic 'Failed to get rooms from svf2' 메시지로 throw한다. 이는 특정 BIM 모델의 SVF2 변환 결과물에 property database 메타데이터 불일치가 있을 때 발생하는 데이터 의존적 문제이다.

Technical Analysis#

Code Path#

• Entry point: room-service.ts:68 — this.runRoomExtractor(cpBim) 호출
• room-service.ts:187 — RoomExtractManager.execute(params) 호출
• room-extract.manager.ts:29 — ChildProcessManager.execute('execute', params) → child process로 메시지 전달
• room-extractor.process.ts:40 — ForgeAgent.extract(params.apiConfig, params.urn, {...}) 호출
• Failure point: room-extractor.process.ts:52 — throw new Error('Failed to get rooms from svf2')

ForgeAgent.extract()가 SVF2 모델의 property database를 순회하면서 내부적으로 object ID 19034504를 접근하려 하지만, 해당 모델의 유효 ID 범위는 1~19034503이다. 이 에러가 result.Error에 code 1로 설정되어 반환된다.

if (params.formatType === 'svf2') {
	const result = await ForgeAgent.extract(params.apiConfig, params.urn, {
		extractRoom: true,
		extractMeta: true,
		region: params.region
	});

	if (result.Error == undefined) {
		extract = result;
	} else if (result.Error === ForgeAgentErrorCode.FORGE_SOURCE_INVALID_MANIFEST) {
		this.log('RoomExtractorProcess::execute - svf2 manifest is invalid, try svf1 process');
		extract = await RoomExtractor.room_extract(params.token, params.urn);
	} else {
		throw new Error('Failed to get rooms from svf2');
	}
}

기대 동작: ForgeAgent.extract()가 성공적으로 Room/Level/Meta 정보를 반환하거나, manifest가 invalid한 경우 SVF1 fallback으로 진행.

실제 동작: Forge property database 순회 중 잘못된 object ID 접근으로 code 1 에러가 반환됨. 이 에러 코드는 FORGE_SOURCE_INVALID_MANIFEST가 아니므로 else 분기에서 generic error가 throw됨.

if (response.success) {
	pending.resolve(response.data);
} else {
	pending.reject(new Error(response.error || 'Unknown error'));
}

child process에서 throw된 에러가 IPC를 통해 parent process로 전달되어 RoomExtractManager에서 최종적으로 에러 로그가 기록된다.

Log Evidence#

사용한 Datadog 쿼리:

service:cupixworks-any-room-agent status:error "Failed to get rooms from svf2"

service:cupixworks-any-room-agent

에러 발생 직전 로그 체인 (동일 시각 2026-05-27T09:23:06Z):

Failed to get properties and children: Invalid object ID: 19034504. Valid range is 1 to 19034503.

Failed to get node: Failed to get properties and children

Failed to use property database: Failed to get properties and children

Failed to traverse nodes: Failed to get properties and children

ForgeAgents - Error: { code: 1, message: Failed to get properties and children }

Failed to get rooms from svf2

에러 후 상태 정리 로그:

{
  "message": "BaseService::handlingMessageErrors | Error and message object - {\"error\":\"undefined response\",\"sqsMessage\":{\"MessageId\":\"b6890e21-613b-4fdd-a128-6ec96213fe22\",\"Attributes\":{\"ApproximateReceiveCount\":\"1\"}}}"
}

BaseService::cleanUpAnythingRelatedModel | path: /tmp/workspace/17157

후속 성공 사례 (다른 BIM, 같은 agent 인스턴스, 18:27-18:28):

CPBim::fromRoomExtractor | bim level size: 5, room size: 0

→ 다른 BIM 모델(id: 19642)은 동일 agent에서 정상 처리됨. 이는 agent 자체의 문제가 아닌 특정 BIM 모델의 SVF2 데이터 문제임을 확인.

Hypotheses Considered#

Fix Recommendation#

즉시 조치 (Critical)#

• src/process/room-extractor.process.ts:46-53: result.Error가 FORGE_SOURCE_INVALID_MANIFEST 이외의 에러일 때도 SVF1 fallback을 시도하도록 변경. 현재는 manifest invalid만 fallback하고 나머지는 모두 throw하는데, property database 에러(code: 1)도 SVF1로 fallback할 수 있는 recoverable error이다.

단기 개선 (1주 이내)#

• 에러 메시지에 실제 Forge error code와 메시지를 포함하여 디버깅 용이성 향상. 현재 'Failed to get rooms from svf2'는 원인 파악이 어려움.
• SVF1 fallback 대상 에러 코드 목록을 명시적으로 정의하고, 그 외의 에러는 원본 에러 정보를 포함하여 throw.

장기 개선 (재발 방지)#

• @cupix/forge-agents 라이브러리에서 property database traversal 시 object ID 범위 검증 로직 추가 (off-by-one 방지).
• Forge 에러 코드별 처리 전략을 문서화하고, ForgeErrorMapper 패턴을 room-agent에도 적용하여 일관된 에러 분류 체계 구축.

Monitoring#

• 추가할 메트릭/알림:

  • cupixworks-any-room-agent의 SVF2 extraction 실패율 모니터링
  • SVF1 fallback 빈도 추적

• Datadog 쿼리 예시:

service:cupixworks-any-room-agent status:error "Failed to get rooms from svf2"

service:cupixworks-any-room-agent "svf2 manifest is invalid, try svf1 process"

Risk Assessment#

• Risk level: medium
• 예상 복잡도: standard — SVF1 fallback 조건 확장은 기존 패턴(line 48-50)을 따르면 되지만, 어떤 에러 코드가 recoverable인지 판단이 필요함.