Error Codes
SaigeCycleCounter는 예외를 SaigeToolkit.error.base.SaigeCycleCounterError를 상속한 전용 클래스로 던집니다.
각 예외는 고유한 3자리 코드와 기본 메시지를 가지며, 런타임에는 호출 지점에서 추가 context 문자열이 메시지에 덧붙을 수 있습니다.
6자리 전체 코드
외부 시스템과 주고받을 때는 SaigeToolkit이 부여하는 head(VIMS)와 repo id(39)가 앞에 붙은 6자리 코드로 표기됩니다.
아래 표의 코드는 3자리 클래스 코드입니다.
코드 체계
| 범위 | 카테고리 | 정의 위치 |
|---|---|---|
| 100 – 159 | Build — Trainer / InferenceHandler 빌드 | cycle_counter/errors/e100_build.py |
| 200 – 299 | Data — 비디오/프레임 스토리지, 라벨 | cycle_counter/errors/e200_data.py |
| 300 – 349 | Frame Selector | cycle_counter/errors/e300_modules_frame_selector.py |
| 350 – 399 | Sequence Monitor | cycle_counter/errors/e300_modules_sequence_monitor.py |
| 400 – 499 | Train | cycle_counter/errors/e400_train.py |
| 500 – 549 | Inference | cycle_counter/errors/e500_inference.py |
| 600 – 699 | Model | cycle_counter/errors/e600_model.py |
100 – 159 Build Error
Trainer 또는 InferenceHandler를 생성(build) 하는 과정에서 발생하는 오류.
| 코드 | 클래스 | 의미 / 발생 조건 |
|---|---|---|
| 130 | InferenceHandlerCheckpointNotFoundError |
InferenceHandler가 참조하는 checkpoint 파일이 경로에 없음. |
| 131 | PretrainedWeightsNotFoundError |
사전 학습 가중치가 없음. setup.py를 먼저 실행해 다운로드 필요. |
| 132 | DetectionModelBuildError |
Detection 모델 생성 자체에서 실패. |
| 133 | AnomalyCheckpointRequiredError |
det/iad 타입의 anomaly 모델에 checkpoint_path가 지정되지 않음. |
| 134 | UnsupportedAnomalyModelTypeError |
model_type이 det/iad/cell_checker 외 값. |
| 135 | DuplicateAnomalyMappingError |
동일한 (preceding_model, class_id, offset) 조합에 두 개 이상의 anomaly 모델이 매핑됨. |
200 – 299 Data Error
비디오/프레임 스토리지, 라벨 구조, 시퀀스 데이터 관련 오류.
| 코드 | 클래스 | 의미 / 발생 조건 |
|---|---|---|
| 200 | VideoFrameStorageDeepCopiedError |
메모리 사용량 특성상 VideoFrameStorage는 deep-copy해서는 안 됨. |
| 201 | VideoFramesStorageInconsistentFrameIndexError |
스토리지 내부 frame index가 불일치. 개발자에게 리포트 필요. |
| 202 | InvalidFrameIndicesError |
frame indices의 길이가 시퀀스 길이와 다름. |
| 203 | VideoOpenFailedError |
비디오 파일을 열 수 없음(경로/손상 여부 확인). |
| 204 | InvalidSequenceLengthForTrainingError |
학습 시 시퀀스 길이는 반드시 64여야 함. |
| 205 | InvalidClipInfoError |
clip_dir 또는 clip_path가 제공되지 않음. |
| 206 | InvalidLabelRangeError |
시작 frame index가 끝 frame index보다 큼. |
| 207 | OverlappingLabelRangeError |
이미 라벨된 frame index에 다시 라벨을 부여. |
| 208 | DuplicateFrameIndexError |
다중 target frame이 같은 frame 범위에 중복됨. |
| 209 | InvalidFrameSequenceError |
frame indices가 오름차순이 아니거나 겹침. |
300 – 349 Frame Selector Error
modules/frame_selector의 프레임 저장/선택 로직에서 발생.
| 코드 | 클래스 | 의미 / 발생 조건 |
|---|---|---|
| 300 | DuplicatedTimestampError |
입력 프레임 스토리지에 동일 timestamp가 이미 존재. |
| 301 | TimestampNotFoundError |
요청한 timestamp가 스토리지에 없음. |
| 302 | SelectedFrameDoesNotExistError |
아직 선택된 프레임이 없음. |
| 303 | LengthMismatchError |
timestamps와 frames의 길이가 다름. |
| 304 | TimestampOrderError |
timestamp는 반드시 strictly increasing 순으로 추가되어야 함. |
350 – 399 Sequence Monitor Error
modules/sequence_monitor의 사이클 시퀀스 검증 관련.
| 코드 | 클래스 | 의미 / 발생 조건 |
|---|---|---|
| 350 | EmptyExpectedSequenceError |
expected_sequence가 비어있음. |
| 351 | MissingExpectedSequenceConfigError |
설정에 expected_sequence 또는 expected_class_sequence 키가 없음. |
400 – 499 Train Error
학습 파이프라인(검증 설정, 네트워크 형상 등) 관련.
| 코드 | 클래스 | 의미 / 발생 조건 |
|---|---|---|
| 400 | ValidationNotEnabledError |
검증이 비활성화된 상태에서 검증 프로세스를 요청. |
| 401 | InvalidKernelSizeTypeError |
kernel size 타입이 tuple 또는 tuple list가 아님. |
| 402 | InvalidNetworkShapeConfigurationsError |
네트워크 shape 설정이 잘못됨. |
| 403 | InvalidNetworkOutputTypeError |
네트워크 output type은 sequence-wise 또는 framewise여야 함. |
| 404 | VideoFramesStorageNotGivenError |
Video frame storage가 제공되지 않음. |
500 – 549 Inference Error
추론 파이프라인(옵션, frame selector, detection, anomaly) 관련.
| 코드 | 클래스 | 의미 / 발생 조건 |
|---|---|---|
| 500 | InvalidInferenceOptionError |
유효하지 않은 inference 옵션. |
| 501 | FrameSelectorNotEnabledError |
frame selector가 활성화되지 않음. |
| 502 | InvalidFrameSelectorModeError |
frame selector mode 값이 잘못됨. |
| 503 | DetectionInferenceError |
Detection 추론 내부에서 에러. |
| 504 | DetectionResultRequiredError |
Cell checker가 detection 결과를 요구하지만 제공되지 않음. |
| 505 | UnknownPrecedingModelError |
current_model이 어떤 anomaly 모델의 inference_target.preceding_model에도 등록되지 않음. |
| 506 | AnomalyModelNotMappedError |
preceding_model은 등록됐지만 해당 (class_id, offset) 조합에 매핑된 모델이 없음. |
505 vs 506 구분 가이드
- 505: 설정 파일에
preceding_model이름 자체가 빠져있거나 오타일 때. → YAML에서inference_target.preceding_model항목을 확인. - 506:
preceding_model은 맞지만, 실제 inference에서 들어온class_id또는offset에 대응하는 모델이 정의돼 있지 않을 때. →targets: [{class_id, offset}]매핑을 확인.
600 – 699 Model Error
모델(가중치/아키텍처) 자체의 호환성 관련.
| 코드 | 클래스 | 의미 / 발생 조건 |
|---|---|---|
| 600 | UnsupportedPretrainedWeightsError |
지원하지 않는 pretrained weight. |
사용 예
=== "에러 클래스 직접 catch"
```python
from cycle_counter.errors import error
try:
detector = VisualAnomalyDetector.build(config)
except error.AnomalyCheckpointRequiredError as e:
# 133 — checkpoint_path 누락
logger.error(f"설정 오류: {e.message}")
raise
except error.DuplicateAnomalyMappingError as e:
# 135 — 중복 매핑
logger.error(f"설정 오류: {e.message}")
raise
```
=== "코드로 분기"
```python
from cycle_counter.errors import error
from SaigeToolkit.error.base import SaigeCycleCounterError
try:
result = detector.infer(cycle_info)
except SaigeCycleCounterError as e:
if e.code == "505":
# preceding_model 자체가 미등록
handle_config_missing()
elif e.code == "506":
# class/offset 매핑 누락
handle_mapping_missing()
else:
raise
```