ES /docs

ChildProcessManager::setupEventHandlers | Child process stderr: Cannot find geometry 3d entity from

RCA: Cannot find geometry 3d entity from manifest

Error Log#

Datadog Logs

text
ChildProcessManager::setupEventHandlers | Child process stderr: Cannot find geometry 3d entity from manifest.

Impact#

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

Root Cause Summary#

cupix-tesla-mesh-agent가 BIM 모델(ID 18884, 18885, 18886)의 mesh 추출을 위해 네이티브 C++ 라이브러리 @cupix-compute/forge_bimmodel_extractor(v0.0.148)의 process() 메서드를 호출했으나, 해당 BIM 모델의 Forge manifest에서 geometry 3D entity를 찾지 못해 false를 반환하며 실패했습니다. 이 에러는 flintbuilders 팀(user: mmorrison@flintbuilders.com)이 업로드한 특정 BIM 모델들에서만 발생했으며, 동일 시간대에 처리된 updatedemo 팀의 BIM 18883은 성공적으로 16개 mesh 파일을 추출했습니다. 이는 특정 BIM 모델의 Forge 변환 결과물에 geometry 3D entity가 누락되어 있는 데이터 문제로 판단됩니다.

Technical Analysis#

Code Path#

  • Entry point: mesh-service.ts:101 — MeshService::run() 에서 BIM ID로 처리 시작
  • mesh-service.ts:112 — runMeshExtractor(cpBim) 호출
  • mesh-service.ts:184-194 — MeshExtractManager::execute()에 Forge URN, format type, region 등 파라미터 전달
  • mesh-extract.manager.ts:70 — ChildProcessManager::execute() 를 통해 자식 프로세스로 전달
  • mesh-extractor.process.ts:126-150 — 자식 프로세스에서 forge_bimmodel_extractor의 process() 호출
  • Failure point: mesh-extractor.process.ts:138 — extractBIMModel.process()가 false 반환

실행 흐름:

  1. SQS 큐(cupix-tesla-mesh-agent-production)에서 BIM ID를 수신
  2. Tesla API에서 BIM 메타데이터(Forge URN, format type 등) 조회
  3. Forge 인증 후 자식 프로세스에서 mesh 추출 실행
  4. 네이티브 라이브러리가 Forge manifest를 파싱하여 geometry 3D entity 검색
  5. geometry 3D entity를 찾지 못해 stderr로 에러 메시지 출력 후 process()가 false 반환

자식 프로세스의 mesh 추출 코드:

typescript
// 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();  // false 반환 시 실패

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

에러 발생 후 MeshService::run()의 catch 블록에서 mesh_state를 error로 업데이트:

typescript
// packages/cupix-tesla-mesh-agent/src/mesh-service.ts:110-121
try {
    await this.forgeAuth.authenticate();
    await this.runMeshExtractor(cpBim);
    // ...
} catch (error) {
    logger.error('MeshService::run | error: %s', JSON.stringify(error, Object.getOwnPropertyNames(error)));
    await this.updateErrorState(cpBim);
}

stderr 로깅은 ChildProcessManager에서 pipe 모드로 캡처:

typescript
// packages/base/src/manager/child-process.manager.ts:138-141
this.process.stderr?.on('data', (data: Buffer) => {
    const text = data.toString();
    logger.error(`ChildProcessManager::setupEventHandlers | Child process stderr: ${text}`);
});

기대 동작: forge_bimmodel_extractor가 Forge manifest에서 geometry 3D entity를 찾아 mesh 파일을 추출하고 process()가 true를 반환해야 합니다.

실제 동작: 네이티브 라이브러리가 manifest에서 geometry 3D entity를 찾지 못해 stderr에 "Cannot find geometry 3d entity from manifest." 메시지를 출력하고 process()가 false를 반환했습니다. 이로 인해 MeshExtractorProcess에서 Error가 throw되고, MeshService가 BIM의 mesh_state를 error로 업데이트했습니다.

Log Evidence#

사용한 Datadog 쿼리:

text
service:cupixworks-any-mesh-agent status:error @environment:production
text
service:cupixworks-any-mesh-agent status:info @environment:production

실패 케이스 — BIM 18884 (flintbuilders):

text
[2026-04-06T15:01:59.229Z] BaseService::runByMessage | id: 18884
[2026-04-06T15:01:59.258Z] CupixAuth::setSession | session_id: c1e5b327f7f4650645381c7098139d2df23f3e05
[2026-04-06T15:01:59.619Z] ChildProcessManager::setupEventHandlers | Child process stderr: sentry initialization failed.
[2026-04-06T15:02:00.483Z] ChildProcessManager::setupEventHandlers | Child process stderr: Cannot find geometry 3d entity from manifest.
[2026-04-06T15:02:00.486Z] forge_bimmodel_extractor failed to extract mesh, process() returned: false
[2026-04-06T15:02:00.486Z] 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)..."}
[2026-04-06T15:02:00.707Z] BaseService::cleanUpAnythingRelatedModel | path: /tmp/workspace/18884

실패 케이스 — BIM 18886 (flintbuilders):

text
[2026-04-06T15:16:39.788Z] BaseService::runByMessage | id: 18886
[2026-04-06T15:16:43.168Z] ChildProcessManager::setupEventHandlers | Child process stderr: Cannot find geometry 3d entity from manifest.
[2026-04-06T15:16:43.174Z] forge_bimmodel_extractor failed to extract mesh, process() returned: false

실패 케이스 — BIM 18885 retry (flintbuilders, host: ip-10-1-160-108):

text
[2026-04-06T15:16:43.963Z] BaseService::runByMessage | id: 18885
[2026-04-06T15:16:45.359Z] ChildProcessManager::setupEventHandlers | Child process stderr: Cannot find geometry 3d entity from manifest.
[2026-04-06T15:16:45.361Z] forge_bimmodel_extractor failed to extract mesh, process() returned: false

성공 케이스 — BIM 18883 (updatedemo):

text
[2026-04-06T14:21:37.130Z] BaseService::runByMessage | id: 18883
[2026-04-06T14:29:21.238Z] CPBim::fromMeshExtractor | filepaths count: 16
[2026-04-06T14:32:41.110Z] MeshService::uploadBimMeshArchiveFile | end
[2026-04-06T14:32:42.385Z] AwsQueueManager::deleteMessage | end

주요 관찰:

  • BIM 18884, 18886은 CPBim::fromMeshExtractor 로그가 없음 — 추출 자체가 실패
  • BIM 18885는 첫 번째 시도(ip-10-1-34-2)에서 성공(16 파일 추출, 업로드 완료)했지만, 두 번째 시도(ip-10-1-160-108)에서 동일 에러로 실패. 첫 번째 시도 시 "Warning: Offset out of bounds (offset: 13886126080, buffer size: 80)" 경고가 발생한 점에서 해당 BIM 모델의 geometry 데이터가 경계 조건에 있음을 시사
  • 모든 실패는 동일 팀(flintbuilders), 동일 사용자(mmorrison@flintbuilders.com), 동일 세션에서 발생
  • SQS 메시지는 에러 발생 후에도 삭제됨 — 재시도 로직이 SQS visibility timeout에 의존

Fix Recommendation#

즉시 조치 (Critical)#

  • mesh-extractor.process.ts:148-150 — 현재 process()가 false를 반환할 때 generic error만 throw하고 있음. stderr에서 캡처된 구체적인 에러 메시지("Cannot find geometry 3d entity from manifest")를 에러 메시지에 포함시켜 디버깅을 용이하게 해야 함
  • mesh-service.ts:117-120 — catch 블록에서 에러를 로깅하고 mesh_state를 error로 변경하지만, 구체적인 에러 사유(manifest에서 geometry entity 미발견)를 BIM 레코드에 저장하지 않음. Tesla API에 에러 상세를 전달하는 방안 검토 필요

단기 개선 (1주 이내)#

  • forge_bimmodel_extractor가 stderr로 출력하는 에러 메시지를 구조화하여 자식 프로세스 → 부모 프로세스로 전달하는 메커니즘 추가. 현재 stderr 로그는 ChildProcessManager에서 캡처되지만 process() 반환값과 연결되지 않아, 실패 원인을 로그에서 수동으로 찾아야 함
  • flintbuilders 팀의 BIM 18884, 18886 모델에 대해 Forge manifest 상태 확인 필요 — Autodesk Model Derivative API로 manifest를 조회하여 geometry 3D viewable이 존재하는지 검증
  • BIM 18885의 경우 첫 시도 성공 후 재처리된 원인 조사 필요 — SQS 메시지 중복 전달 또는 다른 트리거에 의한 것인지 확인

장기 개선 (재발 방지)#

  • mesh 추출 전에 Forge Model Derivative API를 통해 manifest의 geometry 3D viewable 존재 여부를 사전 검증하는 pre-check 단계 추가. manifest에 geometry가 없는 경우 추출을 시도하지 않고 적절한 에러 상태와 사유를 기록
  • @cupix-compute/forge_bimmodel_extractor 네이티브 라이브러리(v0.0.148)의 에러 핸들링 개선 — process() 메서드가 단순 boolean 대신 구조화된 에러 정보를 반환하도록 업데이트 검토
  • BIM 모델의 Forge 변환 완료 상태를 더 세밀하게 추적하여, 변환은 완료되었으나 geometry viewable이 없는 케이스(2D-only 모델 등)를 별도로 처리

Monitoring#

  • mesh 추출 실패율 모니터링:
text
service:cupixworks-any-mesh-agent "forge_bimmodel_extractor failed to extract mesh" status:error
  • manifest geometry entity 미발견 에러 추적:
text
service:cupixworks-any-mesh-agent "Cannot find geometry 3d entity from manifest" status:error
  • 팀별 실패율 비교를 위한 대시보드 쿼리:
text
service:cupixworks-any-mesh-agent status:error @environment:production

Risk Assessment#

  • Risk level: low
  • 예상 복잡도: standard
  • 특정 BIM 모델의 Forge manifest 구조 문제로 인한 데이터 의존적 에러. flintbuilders 팀의 특정 모델에만 영향을 미치며, 서비스 전체 안정성에는 영향 없음. 에러 발생 시 mesh_state가 error로 업데이트되어 상태 관리는 정상 동작하나, 사용자에게 구체적인 실패 사유가 전달되지 않는 점이 개선 필요.