PreprocessorService::checkSupportedVideo | end - found unsupported video - AGT5116

RCA: PreprocessorService::checkSupportedVideo | found unsupported video - AGT5116

Overview#

What Happened#

2026-04-21 09:43:07 KST에 cupixworks-capture-preprocessor-agent 서비스에서 capture ID 684302의 비디오 전처리 중 네이티브 scenemapper 라이브러리가 "Single fisheye video detected"로 비디오를 지원 불가 판정하여 AGT5116 에러 코드와 함께 작업이 실패했다. 이는 사용자가 지원되지 않는 단일 fisheye 카메라 비디오를 업로드한 것에 대한 정상적인 입력 검증 동작이다.

Quick Facts#

Field	Value
exception.message	`Single fisheye video detected.`
top_frame	`preprocessor-service.ts:752 (dist)`
env	production, us-west-2
error_code	`AGT5116`
capture_id	`684302`

Timeline#

09:42:47 KST — BaseService가 job ID 1025853으로 capture 684302 처리 시작
09:42:50 KST — 비디오 1개 로드 완료 (loadVideos | video count: 1)
09:42:57 KST — scenemapper options 설정 시 entity_parameter 비어있음 (warn)
09:43:07 KST — checkSupportedVideo가 네이티브 라이브러리 호출 후 status_code 116 반환, "Single fisheye video detected" 에러 throw
09:43:08 KST — BaseService::handlingMessageErrors가 에러 처리, SQS 메시지 삭제

Error Log#

Datadog Logs

text

PreprocessorService::checkSupportedVideo | end - found unsupported video - AGT5116

Impact#

Service: cupixworks-capture-preprocessor-agent
발생 횟수: 1 (이 클러스터), 지난 7일간 총 3회 발생
최초 발생: 2026-04-21T00:43:07.213Z
최근 발생: 2026-04-21T00:43:07.213Z

Root Cause Summary#

사용자가 단일 fisheye 카메라로 촬영한 비디오를 업로드하여 전처리를 요청했다. checkSupportedVideo 메서드가 네이티브 C++ scenemapper 라이브러리(PreprocessorApi.is_supported_video)를 호출하여 비디오를 검증한 결과, status_code 116("Single fisheye video detected")이 반환되었다. 코드는 status_code > 0일 때 지원 불가로 판정하고 AGT5{status_code} 형식으로 에러 코드를 생성하며 logger.error로 기록 후 예외를 throw한다. 이는 의도된 입력 검증 동작이며, 지원되지 않는 비디오 포맷에 대한 정상적인 거부 처리이다. 다만 이를 error 레벨로 로깅하는 것이 적절한지 재검토가 필요하다.

Technical Analysis#

Code Path#

Entry point: preprocessor-service.ts:145 — run() 메서드 내에서 checkSupportedVideo 호출
비디오 검증 시작: preprocessor-service.ts:824 — 비디오 존재 확인 및 skip_validation 옵션 체크
네이티브 라이브러리 호출: preprocessor-service.ts:851 → preprocessor.manager.ts:98 → preprocessor.process.ts:196
Failure point: preprocessor-service.ts:861-865 — result.status_code > 0 조건 충족 시 에러 로깅 및 throw

packages/cupix-capture-preprocessor-agent/src/preprocessor-service.ts:824-869typescript

private checkSupportedVideo = async (cpCapture: CPCapture): Promise<void> => {
	logger.debug('PreprocessorService::checkSupportedVideo | begin');
	if (cpCapture.cpVideos.length < 1) {
		logger.debug('PreprocessorService::checkSupportedVideo | not found videos');
		return;
	}

	const skipValidationOptions = CPUtils.boolean(cpCapture.scenemapperOptionsData?.options?.skip_validation);
	if (skipValidationOptions) {
		logger.debug('PreprocessorService::checkSupportedVideo | skip validation');
		return;
	}

	// ... 비디오 파일을 임시 디렉토리에 복사하고 네이티브 라이브러리 호출 ...

	const result = CPUtils.isJsonString(_data) ? JSON.parse(_data) : undefined;
	if (result.status_code > 0) {
		const _errorCode = ErrorCode.Scenemapper.statusCode(result.status_code.toString());
		this.jobManager.setErrorCode(_errorCode);
		logger.error('PreprocessorService::checkSupportedVideo | end - found unsupported video - %s', _errorCode);
		throw new Error(result.reason);
	}

	logger.info('PreprocessorService::checkSupportedVideo | end');
};

packages/cupix-capture-preprocessor-agent/src/process/preprocessor.process.ts:182-208typescript

private validate(params: any): Promise<any> {
	// ...
	const PreprocessorApi = require(this.libPath);
	const isValid = PreprocessorApi.is_supported_video(
		params.configPath,
		params.outputPath,
		params.inputDirPath
	);
	// ...
}

packages/utils/src/error-code/scenemapper.ts:24-31typescript

export class Scenemapper {
	static readonly Default = 'AGT5000';
	static readonly Initialize = 'AGT5001';
	static readonly Execute = 'AGT5002';
	static readonly Validate = 'AGT5003';
	static readonly AvailableReconstruction = 'AGT5004';
	static readonly statusCode = (code: string): string => `AGT5${code}`;
}

기대 동작: 지원되는 비디오 → status_code 0 반환 → 정상 처리 계속 실제 동작: 단일 fisheye 비디오 → status_code 116 반환 → "Single fisheye video detected" 에러 throw → 작업 실패

Log Evidence#

사용한 Datadog 쿼리:

text

service:cupixworks-capture-preprocessor-agent status:error "checkSupportedVideo"
Time: 2026-04-20T23:30:00Z to 2026-04-21T01:30:00Z

에러 발생 전후 로그 (09:42:47 ~ 09:43:08 KST):

text

09:42:47 [info] BaseService::runByMessage | id: 1025853
09:42:47 [info] CupixAuth::setSession | session_id: 1e1db1f22eb9fb19772245331214a18a1bd74c1b
09:42:50 [info] PreprocessorService::loadVideos | video count: 1
09:42:55 [info] PreprocessorService::setVideoImageMatchData | begin - capture_id: 684302
09:42:57 [warn] CPCapture::overwriteScenemapperOptionsData | entitiy_parameter option is empty
09:43:07 [error] PreprocessorService::checkSupportedVideo | end - found unsupported video - AGT5116
09:43:07 [warn] BaseService::getApiErrorToDeleteMessage | undefined response - {"message":"Single fisheye video detected."}
09:43:08 [error] BaseService::handlingMessageErrors | Error and message object - {"error":"undefined response","sqsMessage":{"MessageId":"96567552-0897-42d1-9a80-fb98ed7def5c"}}

스택트레이스 (warn 로그에서 확인):

text

Error: Single fisheye video detected.
    at PreprocessorService.checkSupportedVideo (/tmp/agent/dist/preprocessor-service.js:752:23)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async PreprocessorService.run (/tmp/agent/dist/preprocessor-service.js:106:17)
    at async BaseService.runByMessage (/tmp/agent/dist/base-service.js:144:17)
    at async BaseService.runByMessages (/tmp/agent/dist/base-service.js:126:17)
    at async BaseService.checkingQueue (/tmp/agent/dist/base-service.js:87:21)
    at async BaseService.init (/tmp/agent/dist/base-service.js:38:13)

지난 7일간 동일 에러 발생 이력 (총 3건):

text

2026-04-21 09:43:07 KST - AGT5116
2026-04-17 12:50:16 KST - AGT5116
2026-04-17 11:34:37 KST - AGT5116

Hypotheses Considered#

#	Hypothesis	Evidence for	Evidence against	Verdict
H1	사용자가 지원되지 않는 단일 fisheye 비디오를 업로드하여 정상적인 입력 검증으로 거부됨	에러 메시지 "Single fisheye video detected.", status_code 116은 네이티브 라이브러리의 명시적 판정, `video count: 1`로 단일 비디오 확인	—	Confirmed
H2	네이티브 scenemapper 라이브러리의 버그로 정상 비디오를 잘못 판별	—	"Single fisheye video detected"는 구체적인 판정 사유를 포함하며, 7일간 3건으로 극히 낮은 빈도. 동일 시간대 다른 비디오는 정상 처리됨 (09:49:41 end 성공 로그 확인)	Rejected
H3	config_works.json 설정 오류로 fisheye 비디오가 지원 목록에서 누락됨	—	이 에러는 설정 문제가 아닌 비디오 자체의 특성(single fisheye)에 대한 판정. 동일 서비스의 다른 캡처는 정상 처리 중	Rejected

Fix Recommendation#

즉시 조치 (Critical)#

불필요: 이 에러는 지원되지 않는 비디오 입력에 대한 정상적인 검증 거부 동작이다. 코드 수정은 필요하지 않다.

단기 개선 (1주 이내)#

preprocessor-service.ts:864의 로그 레벨을 error에서 warn으로 변경 검토. 사용자 입력 검증 실패는 시스템 에러가 아닌 예상된 비즈니스 시나리오이므로 warn 레벨이 더 적절하다. 이렇게 하면 에러 모니터링에서 불필요한 노이즈를 줄일 수 있다.
변경 대상 파일: packages/cupix-capture-preprocessor-agent/src/preprocessor-service.ts:864

장기 개선 (재발 방지)#

클라이언트(앱) 측에서 비디오 업로드 전 사전 검증을 추가하여 지원되지 않는 포맷의 비디오가 서버에 도달하기 전에 사용자에게 안내하는 것을 고려. 이를 통해 불필요한 서버 자원 사용과 사용자 대기 시간을 줄일 수 있다.

Monitoring#

현재 모니터링으로 충분하나, 로그 레벨 변경 시 아래 쿼리로 빈도 추적:

text

service:cupixworks-capture-preprocessor-agent "found unsupported video"

AGT5116 발생 빈도가 급증할 경우 특정 고객의 장비 문제 또는 앱 버전 문제일 수 있으므로 주간 추이 확인 권장.

Risk Assessment#

Risk level: low
예상 복잡도: trivial (로그 레벨 변경만 필요)