RCA: forge_bimmodel_extractor failed to extract mesh, process() returned: false

Error Log#

Datadog Logs

forge_bimmodel_extractor failed to extract mesh, process() returned: false

Impact#

• Service: cupixworks-any-mesh-agent
• Team: flintbuilders
• 발생 횟수: 3
• 최초 발생: 2026-04-06T15:02:00.486Z
• 최근 발생: 2026-04-06T15:16:45.361Z

Root Cause Summary#

forge_bimmodel_extractor 네이티브 라이브러리(@cupix-compute/forge_bimmodel_extractor)가 Autodesk Forge에서 BIM 모델의 SVF2 manifest를 파싱하던 중 "geometry 3d entity"를 찾지 못해 process() 메서드가 false를 반환했다. 이는 특정 BIM 모델(ID: 18884, 18885, 18886)의 Forge manifest에 3D geometry 데이터가 포함되지 않았거나, Forge 서버 측에서 해당 모델의 변환(translation)이 불완전하여 manifest 내에 geometry 3d entity가 누락된 것이 원인이다. child process의 stderr 로그에 "Cannot find geometry 3d entity from manifest." 메시지가 모든 3건의 실패에서 일관되게 출력되었다.

Technical Analysis#

Code Path#

• Entry point: mesh-service.ts:101 — MeshService.run(targetId) SQS 메시지 수신 후 BIM ID로 mesh 추출 시작
• mesh-service.ts:112 — this.runMeshExtractor(cpBim) 호출, Forge 인증 후 mesh 추출 실행
• mesh-service.ts:184 — this.meshExtractManager.execute(params) 호출, child process에 IPC 메시지 전송
• mesh-extract.manager.ts:70 — ChildProcessManager.execute('execute', params) → child process로 extraction 요청
• mesh-extractor.process.ts:126-150 — child process에서 svf2 format 분기, forge_bimmodel_extractor 실행

// packages/cupix-tesla-mesh-agent/src/process/mesh-extractor.process.ts:126-150
if (params.formatType === 'svf2') {
    const extractBIMModel = new BIM_MODEL_EXTRACTOR.extract_bimmodel();
    const envName = CPX_ENVIRONMENT_NAME?.toLowerCase();
    extractBIMModel.setServer(envName);
    extractBIMModel.setModelUrn(params.urn);
    extractBIMModel.setOutputDirpath(params.path);
    const result = extractBIMModel.process();
    if (result === true) {
        const fileList = await CPUtils.getFiles(params.path);
        extract = { filepaths: fileList };
    } else {
        throw new Error(`forge_bimmodel_extractor failed to extract mesh, process() returned: ${result}`);
    }
}

• Failure point: mesh-extractor.process.ts:150 — extractBIMModel.process()가 false를 반환, line 150에서 throw new Error(...) 실행
• 이 에러는 ChildProcessManager의 IPC를 통해 parent process로 전달되고, child-process.manager.ts:182에서 pending.reject(new Error(response.error)) 호출

// packages/base/src/manager/child-process.manager.ts:179-183
if (response.success) {
    pending.resolve(response.data);
} else {
    pending.reject(new Error(response.error || 'Unknown error'));
}

• parent process의 mesh-service.ts:117-120에서 catch 후 error 로그 출력 및 BIM mesh_state를 error로 업데이트

// packages/cupix-tesla-mesh-agent/src/mesh-service.ts:117-120
} catch (error) {
    logger.error('MeshService::run | error: %s', JSON.stringify(error, Object.getOwnPropertyNames(error)));
    await this.updateErrorState(cpBim);
}

• 기대 동작: extractBIMModel.process()가 Forge manifest에서 geometry 3d entity를 찾아 mesh 파일을 추출하고 true를 반환
• 실제 동작: manifest에 geometry 3d entity가 없어 false 반환, stderr에 "Cannot find geometry 3d entity from manifest." 출력

Log Evidence#

Datadog 검색 쿼리:

service:cupixworks-any-mesh-agent status:error "forge_bimmodel_extractor failed to extract mesh"

service:cupixworks-any-mesh-agent "MeshService"

service:cupixworks-any-mesh-agent "Cannot find geometry 3d entity from manifest"

3건의 에러 모두 동일한 패턴으로, child process stderr에서 "Cannot find geometry 3d entity from manifest." 메시지가 먼저 출력된 후 process() 반환값 false로 인해 에러가 발생:

{
  "timestamp": "2026-04-07 00:02:00 KST",
  "status": "error",
  "message": "ChildProcessManager::setupEventHandlers | Child process stderr: Cannot find geometry 3d entity from manifest."
}

{
  "timestamp": "2026-04-07 00:02:00 KST",
  "status": "error",
  "message": "forge_bimmodel_extractor failed to extract mesh, process() returned: false"
}

{
  "timestamp": "2026-04-07 00:02:00 KST",
  "status": "error",
  "message": "MeshService::run | error: {\"stack\":\"Error: forge_bimmodel_extractor failed to extract mesh, process() returned: false\n    at ChildProcessManager2.handleMessage (/tmp/agent/dist/app.cjs:1564:26)\"}"
}

영향 받은 BIM ID 및 타임라인:

주목할 점: BIM 18885는 00:00:31에 처리 시작하여 00:01:58에 upload까지 성공했으나, 00:16:43에 재처리 시 실패했다. 이는 SQS 메시지가 재전달(redelivery)되어 동일 모델이 다시 처리되었을 가능성을 시사한다.

추가로 child process stderr에서 "sentry initialization failed." 경고가 모든 실행에서 나타나지만 이는 에러의 직접 원인은 아닌 부수 경고이다:

{
  "timestamp": "2026-04-07 00:16:44 KST",
  "status": "error",
  "message": "ChildProcessManager::setupEventHandlers | Child process stderr: sentry initialization failed."
}

Fix Recommendation#

즉시 조치 (Critical)#

• mesh-extractor.process.ts:148-150 — process()가 false를 반환할 때 child process stderr 내용을 에러 메시지에 포함시켜야 한다. 현재는 process() returned: false만 전달되어 "Cannot find geometry 3d entity from manifest."라는 실제 원인이 parent process의 에러 로그에 표시되지 않는다.
• 영향 받은 BIM 모델(18884, 18885, 18886)의 Forge URN이 유효한지, Forge 서버에서 해당 모델의 translation이 정상 완료되었는지 확인이 필요하다.

단기 개선 (1주 이내)#

• mesh-extractor.process.ts에서 extractBIMModel.process() 호출 전에 Forge manifest를 사전 검증하여, geometry 3d entity가 존재하지 않는 모델은 추출 시도 전에 사전 차단하고 명확한 에러 메시지를 반환하도록 한다.
• mesh-service.ts:101-122의 run() 메서드에서 에러 발생 시 BIM ID, Forge URN, format type 등 context 정보를 에러 로그에 포함시켜 디버깅을 용이하게 한다 (현재는 error object만 직렬화).
• SQS 메시지 중복 전달(redelivery) 시 이미 성공한 BIM 모델의 재처리를 방지하는 idempotency 체크 추가 — mesh_state가 이미 extracted인 경우 skip.

장기 개선 (재발 방지)#

• Forge 모델 업로드/변환 파이프라인에서 translation 완료 후 geometry 3d entity 존재 여부를 검증하는 validation step 추가. manifest에 geometry가 없는 모델은 mesh 추출 대기열에 넣지 않도록 한다.
• forge_bimmodel_extractor 네이티브 라이브러리의 에러 리포팅 개선 — process() 반환값 false 외에 구체적인 실패 사유를 프로그래매틱하게 조회할 수 있는 API 제공 필요.

Monitoring#

• forge_bimmodel_extractor 실패율 추적:

service:cupixworks-any-mesh-agent status:error "forge_bimmodel_extractor failed to extract mesh"

• geometry 3d entity 누락 특정 모니터링:

service:cupixworks-any-mesh-agent "Cannot find geometry 3d entity from manifest"

• mesh extraction 성공/실패 비율 메트릭 추가 권장 (현재는 로그 기반으로만 추적 가능)

Risk Assessment#

• Risk level: low
• 예상 복잡도: standard
• 이 에러는 특정 BIM 모델의 Forge manifest에 geometry 3d entity가 누락된 데이터 문제이며, 시스템 전체에 영향을 미치지 않는다. 에러 발생 시 BIM mesh_state가 error로 정상 업데이트되어 다운스트림 프로세스에 전파되지 않는다. 단, 에러 메시지에 실제 원인("Cannot find geometry 3d entity")이 포함되지 않아 디버깅 효율이 낮은 점은 개선 필요.