RCA: MeshService::run | Cannot read properties of undefined (reading 'filepaths')

Overview#

What Happened#

2026-04-22T00:07:16Z에 cupixworks-any-mesh-agent 서비스에서 BIM ID 3309의 mesh 추출 작업이 실패했다. 자식 프로세스(MeshExtractorProcess)가 legacy SVF 경로로 실행되었으나, @cupix/app-mesh-extractor-v2의 mesh_extract() 함수가 undefined를 반환하여 extract.filepaths 접근 시 TypeError가 발생했다.

Quick Facts#

Affected Teams#

Timeline#

1. 2026-04-22T00:07:14Z — SQS 메시지 수신, BIM ID 3309 처리 시작 (BaseService::runByMessage)
2. 2026-04-22T00:07:14Z — mesh_state를 extracting으로 업데이트
3. 2026-04-22T00:07:14Z — 자식 프로세스 fork (PID 48, mesh-extractor.process.cjs)
4. 2026-04-22T00:07:16Z — 자식 프로세스 ready, execute 시작
5. 2026-04-22T00:07:16Z — legacy SVF 경로 진입, mesh_extract() 호출 → TypeError 발생
6. 2026-04-22T00:07:16Z — mesh_state를 error로 업데이트, 워크스페이스 정리, SQS 메시지 삭제

Error Log#

Datadog Logs

MeshService::run | error: {"stack":"Error: Cannot read properties of undefined (reading 'filepaths')
    at ChildProcessManager2.handleMessage (/tmp/agent/dist/app.cjs:1565:26)
    at ChildProcess.<anonymous> (/tmp/agent/dist/app.cjs:1503:16)
    at ChildProcess.emit (node:events:524:28)
    at ChildProcess.emit (node:domain:489:12)
    at emit (node:internal/child_process:950:14)
    at process.processTicksAndRejections (node:internal/process/task_queues:83:21)","message":"Cannot read properties of undefined (reading 'filepaths')"}

Impact#

• Service: cupixworks-any-mesh-agent
• Team: multiplex-global
• 발생 횟수: 1
• 최초 발생: 2026-04-22T00:07:16.397Z
• 최근 발생: 2026-04-22T00:07:16.397Z

Root Cause Summary#

BIM ID 3309의 forge_format_type이 svf2가 아닌 legacy SVF 포맷이어서, MeshExtractorProcess.execute()가 legacy 경로(MeshExtractor.mesh_extract())로 분기했다. 이 경로에서는 Forge OAuth token이 필요하지만, 부모 프로세스(MeshService.runMeshExtractor)가 token 파라미터를 전달하지 않아 undefined로 호출되었다. mesh_extract()가 undefined를 반환하면서, 후속 코드 extract.filepaths 접근 시 TypeError가 발생했다.

Technical Analysis#

Code Path#

• Entry point: mesh-service.ts:101 — MeshService.run(targetId)
• mesh-service.ts:112 — this.runMeshExtractor(cpBim) 호출
• mesh-service.ts:184-194 — meshExtractManager.execute(params) 호출, token 파라미터 없음
• mesh-extract.manager.ts:70 — childProcessManager.execute('execute', params) IPC 전송
• mesh-extractor.process.ts:118 — 자식 프로세스 execute() 진입
• mesh-extractor.process.ts:126 — params.formatType === 'svf2' 조건 검사 — false
• Failure point: mesh-extractor.process.ts:153 — legacy 경로 MeshExtractor.mesh_extract(params.token!, ...) 호출
• mesh-extractor.process.ts:156-157 — extract.filepaths 접근 시 TypeError

부모 프로세스(MeshService.runMeshExtractor)가 자식 프로세스에 전달하는 파라미터:

const meshExtractorResults = await this.meshExtractManager.execute({
    apiConfig:{
        clientId: Environment.ADF_CLIENT_ID,
        clientSecret: Environment.ADF_CLIENT_SECRET
    },
    urn: cpBim.forgeUrn,
    path: cpBim.meshDirPath,
    timeOut: Environment.CPX_EXTRACTOR_TIMEOUT,
    formatType: cpBim.forgeFormatType,
    region: cpBim.forgeRegion
});

token 필드가 누락되어 있다. MeshExtractorParams 인터페이스에도 token이 정의되어 있지 않다:

export interface MeshExtractorParams {
    apiConfig: {
        readonly clientId: string;
        readonly clientSecret: string;
    };
    urn: string;
    path: string;
    timeOut: number;
    formatType: string;
    region: string;
}

자식 프로세스의 ExtractorParams 인터페이스에서는 token이 optional로 정의되어 있으나, legacy 경로에서는 이를 non-null assertion(!)으로 사용한다:

if (params.formatType === 'svf2') {
    // svf2 경로: forge_bimmodel_extractor 사용 (token 불필요)
    // ... 성공적인 추출 후 filepaths 반환
} else {
    // legacy 경로: token이 필수지만 undefined로 전달됨
    extract = await MeshExtractor.mesh_extract(params.token!, params.urn, params.timeOut!, params.path);
}

const extractorResults = {
    filepaths: extract.filepaths  // extract가 undefined이면 TypeError
};

성공한 실행(BIM 2848)은 forge_format_type이 svf2여서 svf2 경로를 탔고, process() 결과가 true로 정상 추출되었다.

Log Evidence#

Datadog에서 수집한 에러 로그:

Datadog query: service:cupixworks-any-mesh-agent status:error
Time: 2026-04-21T23:00:00Z to 2026-04-22T01:30:00Z

{
  "timestamp": "2026-04-22 09:07:16 KST",
  "status": "error",
  "message": "MeshService::run | error: {\"stack\":\"Error: Cannot read properties of undefined (reading 'filepaths')\\n    at ChildProcessManager2.handleMessage (/tmp/agent/dist/app.cjs:1565:26)\\n    at ChildProcess.<anonymous> (/tmp/agent/dist/app.cjs:1503:16)\"}"
}

Watch/Kibana에서 수집한 debug 로그가 핵심 증거이다. 실패한 BIM 3309의 자식 프로세스 실행 흐름:

Kibana query: ("MeshExtractorProcess::execute") AND level:debug
Index: logstash-agents*
Time: 2026-04-22T00:05:00Z → 2026-04-22T00:10:00Z

[09:07:16] [Child] MeshExtractorProcess::execute | start
[09:07:16] [Child] MeshExtractorProcess::execute | error: Cannot read properties of undefined (reading 'filepaths')
[09:07:16] [Child] MeshExtractorProcess::execute | stack: TypeError: Cannot read properties of undefined (reading 'filepaths')
    at MeshExtractorProcess.execute (/tmp/agent/dist/process/mesh-extractor.process.cjs:6361:28)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async MeshExtractorProcess.processMessage (/tmp/agent/dist/process/mesh-extractor.process.cjs:6303:16)
    at async MeshExtractorProcess.handleMessage (/tmp/agent/dist/process/mesh-extractor.process.cjs:5798:26)

execute | start 직후 에러가 발생했고, svf2 경로에서 출력되는 forge_bimmodel_extractor params 로그가 없다. 이는 params.formatType !== 'svf2'를 의미한다.

성공한 BIM 2848과 비교:

Kibana query: ("MeshExtractorProcess::execute") AND level:debug
Index: logstash-agents*
Time: 2026-04-21T23:14:00Z → 2026-04-21T23:22:00Z

[08:16:43] [Child] MeshExtractorProcess::execute - process() result: true (boolean)
[08:16:43] [Child] MeshExtractorProcess::execute - extracted 64 files: ["/tmp/workspace/2848/mesh/AECModelData.json", ...]
[08:16:43] [Child] MeshExtractorProcess::execute | Mesh extraction completed successfully

BIM 2848은 svf2 경로로 정상 추출되었다. process() result: true 로그는 svf2 전용이다.

Hypotheses Considered#

Fix Recommendation#

즉시 조치 (Critical)#

• mesh-extractor.process.ts:153 — legacy SVF 경로에서 params.token이 undefined인 경우 명시적 에러를 throw하도록 guard 추가. 이렇게 하면 extract.filepaths 접근 시 불명확한 TypeError 대신 원인이 명확한 에러 메시지가 출력된다.
• mesh-extractor.process.ts:156-157 — extract가 undefined일 때의 null check 추가. extract?.filepaths로 안전하게 접근하거나, extract가 undefined이면 명시적 에러 throw.

단기 개선 (1주 이내)#

• mesh-service.ts:174-197 — runMeshExtractor에서 legacy SVF 경로를 위한 Forge OAuth token을 획득하여 token 파라미터로 전달하는 로직 추가. ForgeAuth.authenticate() 호출 후 획득한 token을 params에 포함해야 한다.
• mesh-extract.manager.ts:110-126 — MeshExtractorParams 인터페이스에 token?: string 필드 추가.
• 또는 legacy SVF 포맷의 BIM 모델이 더 이상 지원되지 않는다면, formatType !== 'svf2'일 때 명시적으로 지원 중단 에러를 throw하고 불필요한 legacy 코드 경로를 제거하는 것이 더 깔끔한 접근이다.

장기 개선 (재발 방지)#

• legacy SVF 포맷의 BIM 모델이 시스템에 얼마나 있는지 조사하여, 지원 여부를 결정. svf2 전환이 완료되었다면 legacy 경로를 제거.
• forge_format_type별 처리 결과를 메트릭으로 수집하여, 어떤 포맷의 모델이 실패하는지 모니터링.

Monitoring#

• mesh_extract 실패율을 forge_format_type별로 추적하는 메트릭 추가
• Datadog 알림 쿼리:

service:cupixworks-any-mesh-agent status:error "Cannot read properties of undefined"

service:cupixworks-any-mesh-agent status:error "MeshService::run"

Risk Assessment#

• Risk level: medium
• 예상 복잡도: standard — legacy SVF 경로의 token 전달 로직 추가 또는 legacy 경로 제거 판단이 필요