RCA: CompareExtractor Bounding Box Validation Failure

Overview#

What Happened#

2026-05-26 16:08:09 UTC에 cupixworks-any-bimrevision-agent 서비스에서 BIM revision 비교 작업 중 source model의 bounding box가 허용 한도(5,000m)를 크게 초과(645,970.2m)하여 ForgeAgentError (error code 908)가 발생했다. 비교 대상은 BIM revision 23701 (현재)과 19729 (이전)이며, Fortis Construction 팀의 프로젝트에서 1건 발생했다.

Quick Facts#

Affected Teams#

Timeline#

1. 2026-05-26T16:08:04Z — Child process 시작 (AWS SDK v2 deprecation warning 발생)
2. 2026-05-26T16:08:09Z — CompareExtractor.compare() 실행 중 validateBoundsSize() 에서 bounding box 크기 초과 감지, ForgeAgentError(908) throw
3. 2026-05-26T16:08:09Z — 상위 서비스에서 error code 908을 REV908으로 매핑, BIM revision 상태를 Error로 업데이트
4. 2026-05-27 — Error Sweeper에 의해 자동 감지 및 RCA 수행

Error Log#

Datadog Logs

ChildProcessManager::setupEventHandlers | Child process stderr:     at CompareExtractor.compare (/tmp/agent/dist/node_modules/.pnpm/@cupixapps+forge-agents@10.98.0_@cupixapps+forge-utils@10.98.0_axios@1.16.1_commander@3_98c5605cf7877eebfad9715227997162/node_modules/@cupixapps/forge-agents/extractor/compare-extractor/compare-extractor.js:58:50)

Impact#

• Service: cupixworks-any-bimrevision-agent
• Team: fortis
• 발생 횟수: 1
• 최초 발생: 2026-05-26T16:08:09.080Z
• 최근 발생: 2026-05-26T16:08:09.080Z

Root Cause Summary#

BIM revision 23701의 source model bounding box 최대 범위가 645,970.2m로, @cupixapps/forge-agents 패키지의 validateBoundsSize() 함수에서 설정된 5,000m 한도를 약 129배 초과했다. 이는 업로드된 BIM 모델의 좌표계 또는 단위 설정이 잘못되었음을 의미한다 (예: mm 단위 모델이 m 단위로 해석됨, 또는 절대 좌표계 사용). forge-agents 패키지는 이러한 대규모 모델에서 floating-point precision 문제로 비교 결과가 신뢰할 수 없다는 것을 방지하기 위해 의도적으로 이 validation guard를 두고 있으며, 에러 핸들링은 정상 동작한다.

Technical Analysis#

Code Path#

1. Entry point — SQS 메시지 수신 후 BimRevisionService::run 실행

   • bim-revision-service.ts:150 — run(targetId, msgObject) 시작

2. 비교 실행 — runBimCompare()에서 child process에 비교 위임

const bimCompareResults = await this.bimCompareManager.execute(params);

3. Child process — BimCompareProcess::execute에서 ForgeAgent.extract() 호출

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
    }
});

4. Failure point — @cupixapps/forge-agents 내부의 validateBoundsSize() → CompareExtractor.compare()

ForgeAgentError: The source model bounding box is too large for reliable comparison (max extent: 645970.2m, limit: 5000m)
    at Object.validateBoundsSize (compare-utils.js:60:19)
    at CompareExtractor.compare (compare-extractor.js:58:50)
    at async extractComparison (app.js:133:20)
    at async Object.extract (app.js:82:25)
    at async BimCompareProcess.execute (bim-compare.process.cjs:6459:22)

5. 에러 전파 — child process에서 throw된 에러가 ForgeAgent.Result.Error(908) + ErrorMessage로 부모에게 반환됨

if (forgeErrorCode) {
    if (ForgeErrorMapper.isIgnorableError(forgeErrorCode)) {
        logger.warn('BimRevisionService::runBimCompare | Ignorable Forge error detected...');
    } else {
        const errorCode = ForgeErrorMapper.mapForgeErrorToRevisionError(forgeErrorCode);
        logger.error('BimRevisionService::runBimCompare | Critical Forge error detected...');
        this.setErrorCode(errorCode);
        throw new Error(`BimRevisionService::runBimCompare | Forge error: ${forgeErrorCode} - ${forgeErrorMessage}`);
    }
}

6. 최종 처리 — run()의 catch 블록에서 BIM revision 상태를 Error로 업데이트 (error_code: REV908)

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

기대 동작: 정상 크기의 BIM 모델(< 5,000m)을 비교하여 modified/removed/exist 결과를 생성. 실제 동작: source model bounding box가 645,970.2m로 validation 실패 → 에러 코드 908 → REV908으로 매핑 → Error 상태로 정상 전환. 에러 핸들링 자체는 의도된 대로 동작.

Log Evidence#

Datadog 쿼리:

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

시간 범위: 2026-05-26T15:00:00Z ~ 2026-05-26T17:00:00Z

핵심 로그 (호스트: ip-10-1-174-201.us-west-2.compute.internal):

[2026-05-26T16:08:09.080Z] BimRevisionService::runBimCompare | Critical Forge error detected - forgeErrorCode: 908, mapped to revisionErrorCode: REV908

[2026-05-26T16:08:09.083Z] BimRevisionService::run | error: "BimRevisionService::runBimCompare | Forge error: 908 - The source model bounding box is too large for reliable comparison (max extent: 645970.2m, limit: 5000m). Large models cause floating-point precision issues that make comparison unreliable."

컨텍스트 속성:

{
  "session": "dfc40896488a4432a1d64d44af9eb8140437c0d0",
  "bim_revision_id": 23701,
  "previous_bim_revision_id": 19729,
  "team_id": 708,
  "user": "phil.miller@fortisconstruction.com",
  "user_id": 26815,
  "error_code": 908
}

추가: 동일 호스트에서 16:08:04에 AWS SDK v2 deprecation warning 10건도 stderr로 기록됨 (noise, 실제 에러 아님).

Hypotheses Considered#

Fix Recommendation#

즉시 조치 (Critical)#

코드 수정 불필요. 에러 핸들링은 정상 동작하고 있다. 다만 stderr로 출력되는 stack trace가 error 레벨로 로깅되어 error-sweeper에 감지되는 것이 불필요한 noise를 생성한다.

• ChildProcessManager::setupEventHandlers에서 stderr 출력을 error 대신 warn 레벨로 로깅하는 것을 검토. 실제 critical error는 이미 BimRevisionService::runBimCompare 에서 명시적으로 로깅됨.
• 사용자(phil.miller@fortisconstruction.com)에게 BIM 모델의 좌표계/단위를 확인하도록 안내 필요 (BIM revision 23701).

단기 개선 (1주 이내)#

• Child process의 stderr 출력을 warn 레벨로 변경하여 error alert noise 감소. ForgeAgentError가 Result.Error 필드를 통해 정상적으로 부모 프로세스에 전달되므로, stderr stack trace는 중복 정보.
• REV908 에러 발생 시 사용자에게 "모델 좌표계/단위 확인 필요" 가이드 메시지를 UI 레벨에서 제공하는 것을 검토.

장기 개선 (재발 방지)#

• BIM 모델 업로드 시 bounding box 사전 검증 추가 — 비교 단계까지 가기 전에 업로드 시점에서 이상 모델을 거부하면 불필요한 리소스 소비 방지.
• AWS SDK v2 → v3 마이그레이션으로 deprecation warning noise 제거.

Monitoring#

• REV908 에러 빈도를 팀별로 추적하여 특정 팀에서 반복 발생 시 proactive 안내:

service:cupixworks-any-bimrevision-agent "REV908" @environment:production | group by @team

• Child process stderr 에러를 warn으로 변경 후, 실제 critical error만 error 레벨에 남도록 확인:

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

Risk Assessment#

• Risk level: low
• 예상 복잡도: trivial

이 에러는 data quality issue에 대한 정상적인 방어 메커니즘이 작동한 것이며, 서비스 안정성에 영향 없음. 단일 사용자의 단일 모델에만 영향을 미쳤고, 에러 핸들링은 의도대로 동작했다. 주요 개선점은 stderr 로깅 레벨을 warn으로 조정하여 불필요한 error alert를 줄이는 것.