RCA: Forge URN validation failed — BIM model file not found

Overview#

What Happened#

2026-07-18 08:22 KST (production, us-west-2) cupixworks-sitetrack-instance sitetrack-master 에이전트가 sitetrack_id: 21594 작업 중 bim_id: 14742 의 mesh.zip 압축 해제에 실패했고, 뒤이어 실행된 Forge URN 검증이 bim_model.json 부재를 이유로 job 을 중단시켰다. 동일 sitetrack 은 5분 뒤(job_id: 1206941) 자동 재실행에서 정상 통과했으므로 mesh 아카이브의 일시적 손상 또는 다운로드 이슈로 판단된다.

Quick Facts#

Affected Teams#

Timeline#

1. 2026-07-18 08:22:11 KST — job_id: 1206942 로드 시작 (sitetrack_id: 21594)
2. 2026-07-18 08:22:16 KST — Sitetrack::createCPSitetrack | begin
3. 2026-07-18 08:22:26 KST — Sitetrack::extractMeshes | failed to extract mesh archive - bim_id: 14742 (warn — swallowed)
4. 2026-07-18 08:22:26 KST — JobManager::updateJobProgress | processingStatus: execute_bim_validator
5. 2026-07-18 08:22:29 KST — ForgeUrnValidator throws BIM model file not found (error)
6. 2026-07-18 08:27:51 KST — 재시도 job_id: 1206941 로드 시작
7. 2026-07-18 08:28:37 KST — Sitetrack::validateForgeUrns | begin (retry)
8. 2026-07-18 08:31:58 KST — Sitetrack::executeBimPointsValidator | end - sitetrack.id: 21594 (retry succeeded)

Error Log#

Datadog Logs

Forge URN validation failed: Error: BIM model file not found: /tmp/workspace/21594/input_data/bim_model/14742/bim_model.json

Impact#

• Service: cupixworks-sitetrack-instance
• Team: tpc
• 발생 횟수: 1
• 최초 발생: 2026-07-18 08:22 KST
• 최근 발생: 2026-07-18 08:22 KST

sitetrack_id 21594 의 초기 실행 1건이 실패했으나, 동일 sitetrack 이 약 5분 뒤 job_id: 1206941 재시도에서 성공했다. 실사용자 데이터 손실은 없고 지연 영향(≈5분)만 발생했다.

Root Cause Summary#

sitetrack-master 에이전트의 extractMeshes 는 개별 BIM 의 mesh.zip 압축 해제가 실패해도 warn 로그만 남기고 다음 BIM 으로 넘어간다 (sitetrack-service.ts:168-171). 이후 validateForgeUrns 는 mesh.zip 이 정상 해제되었음을 전제로 bim_model.json 존재 여부만 검사해 즉시 예외를 던지므로 (forge-urn-validator.ts:48-50), 실제 원인(압축 해제 실패)이 상위 로그에 warn 으로 묻힌 채 sitetrack job 이 fatal 로 실패한다. 실제 로그에서 08:22:26 에 failed to extract mesh archive - bim_id: 14742 warn 이 선행하고 3초 뒤 검증 예외가 발생했다.

Technical Analysis#

Code Path#

Entry point: packages/cupix-sitetrack-master-agent/src/sitetrack-service.ts:87 (Sitetrackservice.run)

실행 흐름:

1. run 이 extractMeshes 로 각 BIM 의 mesh.zip 을 풀어 bim_model.json 을 배치한다.
2. run 이 이어서 validateForgeUrns 로 각 BIM 폴더에 bim_model.json 이 존재하는지 검사한다.
3. extractMeshes 는 오류를 삼키지만, validateForgeUrns 는 파일 부재 시 즉시 throw 한다.

Failure point: packages/cupix-sitetrack-master-agent/src/forge-urn-validator.ts:49

private extractMeshes = async (cpSitetrack: CPSitetrack): Promise<void> => {
  if (!cpSitetrack.meshDirPath) {
    logger.error('Sitetrack::extractMeshes | meshDirPath is undefined');
    throw new Error('meshDirPath is undefined');
  }
  const bimIds = fs.readdirSync(cpSitetrack.meshDirPath, { withFileTypes: true})
    .filter(item => item.isDirectory())
    .map(item => item.name);
  logger.debug('Sitetrack::extractMeshes | begin - bim_ids: %d [%s]', bimIds.length, bimIds.join(', '));
  for (const bimId of bimIds) {
    const meshDirPath = path.join(cpSitetrack.meshDirPath, bimId);
    const meshArchiveFilePath = path.join(meshDirPath, 'mesh.zip');
    if (!fs.existsSync(meshArchiveFilePath)) {
      logger.warn('Sitetrack::extractMeshes | mesh archive file does not exist - bim_id: %s', bimId);
      continue;
    }
    const startTime = Date.now();
    logger.debug('Sitetrack::extractMeshes | begin - bim_id: %s', bimId);
    try {
      await extract(meshArchiveFilePath, { dir: meshDirPath });
    } catch (error) {
      logger.warn('Sitetrack::extractMeshes | failed to extract mesh archive - bim_id: %s', bimId, error);
      continue;
    }
    // ...
  }
};

static validateSingleBimModel(
  workspacePath: string,
  bimModel: IRequestModel
): void {
  const bimModelPath = path.join(
    workspacePath,
    'input_data',
    'bim_model',
    bimModel.id!.toString(),
    'bim_model.json'
  );
  logger.debug('ForgeUrnValidator::validateSingleBimModel | validating BIM %d - path: %s', bimModel.id, bimModelPath);
  if (!fs.existsSync(bimModelPath)) {
    throw new Error(`BIM model file not found: ${bimModelPath}`);
  }
  // ...
}

기대 동작: mesh.zip 안에 bim_model.json 이 함께 포함되어 있고 extract-zip 이 이를 성공적으로 풀어 놓아야 한다. 실제 동작: extract-zip 이 예외를 던졌고 warn 만 남긴 채 bim_model.json 이 만들어지지 않았다. 이어진 검증에서 파일 부재로 fatal 예외가 발생했다.

Log Evidence#

Datadog query:

service:cupixworks-sitetrack-instance "14742"

관측 시각(2026-07-18 08:22 KST) 로그 원문:

2026-07-18 08:22:26  warn   Sitetrack::extractMeshes | failed to extract mesh archive - bim_id: 14742
2026-07-18 08:22:29  warn   ForgeUrnValidator::validateForgeUrns | validation failed - {
  name: 'Error',
  message: 'BIM model file not found: /tmp/workspace/21594/input_data/bim_model/14742/bim_model.json',
  stack: 'Error: BIM model file not found: /tmp/workspace/21594/input_data/bim_model/14742/bim_model.json
    at _ForgeUrnValidator.validateSingleBimModel (/tmp/agent/dist/app.cjs:9662:13)
    at _ForgeUrnValidator.validateForgeUrns (/tmp/agent/dist/app.cjs:9644:28)
    at Sitetrackservice.validateForgeUrns (/tmp/agent/dist/app.cjs:9812:27)
    at Sitetrackservice.run (/tmp/agent/dist/app.cjs:9736:16)
    at async Sitetrackservice.init (/tmp/agent/dist/app.cjs:9691:7)'
}
2026-07-18 08:22:29  error  Forge URN validation failed: Error: BIM model file not found: /tmp/workspace/21594/input_data/bim_model/14742/bim_model.json

동일 sitetrack 의 재시도(job_id: 1206941) 로그 — 실패 5분 뒤 문제없이 통과:

2026-07-18 08:27:57  info   Sitetrack::createCPSitetrack | begin - job_id: 1206941, sitetrack_id: 21594
2026-07-18 08:28:37  info   Sitetrack::validateForgeUrns | begin - sitetrack_id: 21594
2026-07-18 08:28:37  info   Sitetrack::executeBimPointsValidator | begin - sitetrack.id: 21594
2026-07-18 08:31:58  info   Sitetrack::executeBimPointsValidator | end - sitetrack.id: 21594

재시도 성공은 이슈가 mesh 아카이브의 영속적 손상이 아니라 일시적(다운로드 부분 실패, 디스크 IO 순간 오류, 이전 파일 잔존과의 충돌 등)임을 시사한다.

Hypotheses Considered#

Fix Recommendation#

즉시 조치 (Critical)#

• packages/cupix-sitetrack-master-agent/src/sitetrack-service.ts:166-171 — extractMeshes 의 catch 블록이 warn 으로 오류를 삼키고 있다. 정책을 명시적으로 정할 것: (a) 실패한 BIM 을 뒤이은 검증/실행 대상에서 제거하거나, (b) 압축 해제 실패를 곧바로 상위 에러로 승격해 fail-fast + 재시도 궤도로 태우도록 변경. 현재처럼 warn → 이후 단계의 파일 부재 fatal 로 이어지는 흐름은 로그에서 원인 추적을 어렵게 만든다.
• packages/cupix-sitetrack-master-agent/src/forge-urn-validator.ts:48-50 — 파일 부재 예외 메시지에 상관관계(bim_id) 및 상위 extract warn 존재 여부에 대한 힌트를 추가해 운영자가 즉시 근본 원인을 짚을 수 있게 할 것.

단기 개선 (1주 이내)#

• extractMeshes 는 실패한 BIM id 집합을 반환/저장하고, 이후 단계(validateForgeUrns, executeBimValidator) 에서 해당 BIM 을 명시적으로 skip 하거나 job 전체를 조기 실패로 종료하도록 파이프라인을 조정한다.
• mesh 아카이브 다운로드 후 무결성 검증(파일 크기/CRC/bim_model.json 존재 확인)을 preprocessor 단계에 추가해 압축 해제 이전에 손상을 잡아낸다.

장기 개선 (재발 방지)#

• sitetrack 작업 실패 원인 분류: AGT1813 하위에 "mesh extraction failure", "URN mismatch", "missing bim_model.json" 을 구분하는 세부 코드를 추가해 대시보드/자동 재시도 정책을 근본 원인 기반으로 결정.
• extract-zip 실패 로그에 예외 객체 스택을 함께 남겨(현재는 %s 로 렌더된 문자열만 남음) 원인 진단을 개선.

Monitoring#

Datadog 쿼리 예시 — release dashboard timeseries widget 그대로 사용 가능:

service:cupixworks-sitetrack-instance "Sitetrack::extractMeshes | failed to extract mesh archive"

service:cupixworks-sitetrack-instance "BIM model file not found"

service:cupixworks-sitetrack-instance status:error "Forge URN validation failed"

• 위 세 쿼리를 timeseries 로 얹고, 첫 번째(warn) 와 두 번째/세 번째(error) 의 상관 스파이크를 시각화한다.
• 첫 번째 쿼리(extract 실패 warn) 는 알림 임계치 낮게 설정 — 현재 fatal 로 이어지는 유일한 원인 로그이므로 로그 레벨을 error 로 올리기 전까지는 warn 을 별도로 감시해야 한다.

Risk Assessment#

• Risk level: low (자동 재시도로 복구됨, 단일 sitetrack, 데이터 손실 없음)
• 예상 복잡도: standard (에러 전파 정책 변경 + 스킵/조기 실패 분기 추가)