경고
경고 (Warnings)
--warn-error 플래그로 모든 경고를 오류로 승격하거나, --warn-error-options로 세밀하게 제어할 수 있어요. 특정 경고만 오류로 승격하거나 무시(silence)하는 방법을 정리해 드릴게요.
출처: 문서
본문
--warn-error 플래그를 사용하면 모든 경고를 오류로 승격하고, --warn-error-options를 사용하면 옵션으로 세밀하게 제어할 수 있어요.
--warn-error로 모든 경고를 오류로
WARN_ERROR 설정을 활성화하거나 --warn-error 플래그를 설정하면 모든 dbt 경고가 오류로 변환돼요. dbt가 보통 경고할 때마다 대신 오류를 발생시켜요. 예로는 리소스를 선택하지 않는 --select 기준, deprecation, 연관된 모델이 없는 구성, 잘못된 테스트 구성, 또는 경고를 반환하도록 구성된 테스트와 freshness 검사가 있어요.
Usage
dbt run --warn-error
프로덕션 환경에서는 신중히 진행
--warn-error 플래그나 --warn-error-options '{"error": "all"}'를 사용하면 현재와 미래의 모든 경고를 오류로 취급해요. 즉, 향후 dbt 버전에서 새 경고가 도입되면 프로덕션 작업이 예기치 않게 실패할 수 있어요. 프로덕션 환경에서는 주의해서 진행하고, 오류로 취급할 경고만 명시적으로 나열하기를 권장해요.
--warn-error-options로 특정 경고 처리
어떤 경우에는 모든 경고를 오류로 변환하고 싶을 수 있어요. 그러나 일부 경고는 그대로 두고 특정 경고만 승격하거나 무시하고 싶다면 --warn-error-options를 대신 사용할 수 있어요. WARN_ERROR_OPTIONS 설정 또는 --warn-error-options 플래그는 정확히 어떤 유형의 경고를 오류로 취급할지 세밀하게 제어할 수 있게 해줘요.
WARN_ERROR와 WARN_ERROR_OPTIONS는 상호 배타적
WARN_ERROR와 WARN_ERROR_OPTIONS는 상호 배타적이에요. 둘 다(예: env var 또는 플래그) 여러 곳에서 지정하더라도 하나만 지정할 수 있어요. 그렇지 않으면 usage 오류가 표시돼요.
오류로 취급해야 할 경고는 error 매개변수로 지정할 수 있어요. 경고 이름은 다음에서 찾을 수 있어요:
- dbt-labs/dbt의 types.py 파일 —
WarnLevel을 상속하는 각 클래스 이름이 경고 이름에 해당해요 (예: AdapterDeprecationWarning, NoNodesForSelectionCriteria). --log-format json플래그 사용.
(dbt v1.12 이상) v1.12부터 dbt v1은 warn_error_options에서 dbt v2 전용 이름(예: StaticAnalysis, PackageParsingCompatibility)을 오류를 발생시키는 대신 무시하고, <name> is not being used because it's specific to the dbt Fusion engine. 메모를 내보내요. 이를 통해 dbt v1과 dbt v2에서 warn_error_options 구성을 공유할 수 있어요. 진짜 오타는 여전히 오류를 발생시켜요.
(dbt v2.0 이상) dbt v2에서 모든 경고는 숫자 코드(예: 1092)와 이벤트 이름(예: NoNodesForSelectionCriteria)을 모두 가져요. 런타임 메시지는 둘 다 표시하지만, warn_error_options는 이름만 받아요. 이벤트 이름, v2 네이티브 이름, 또는 지원되는 그룹(all, *)을 사용하세요. 숫자 코드는 받지 않으며 오류를 일으켜요. 로그에서 보이는 코드의 이름을 찾으려면 Supported legacy dbt-Core event name aliases를 확인하세요.
error 매개변수는 "all" 또는 "*"로 설정해 모든 경고를 오류로 취급하거나(--warn-error 플래그와 동일), 오류로 취급할 특정 경고 이름 목록으로 설정할 수 있어요.
error가 "all" 또는 "*"로 설정되면 선택적 warn 매개변수로 오류로 취급되는 것에서 제외할 특정 경고를 지정할 수 있어요.
silence 매개변수를 사용해 경고를 무시해요. 무시하고 싶은 특정 경고를 silence 매개변수에 지정할 수 있어요. 이는 특정 경고가 중요하지 않고 무시해도 되는 대규모 프로젝트에서 유용해요. 노이즈를 줄이고 로그를 깨끗하게 유지할 수 있어요.
--warn-error-options 플래그를 사용해 특정 경고를 오류로 승격하는 방법은 다음과 같아요:
--warn-error-options '{"error": ["LogTestResult"]}'플래그로 테스트 경고 테스트.--warn-error-options '{"error": ["JinjaLogWarning"]}'로 Jinja 예외 경고.--warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}'로 선택된 노드 없음.--warn-error-options '{"error": ["Deprecations"]}'로 deprecation 경고 (v1.10에서 새로 추가).
구성 (Configuration)
경고를 오류로 취급하거나 어떤 경고를 무시할지는 명령 플래그, 환경 변수, 또는 dbt_project.yml을 통해 warn error 옵션으로 구성할 수 있어요. 다음 중에서 선택할 수 있어요:
{"error": "all"}또는--warn-error플래그로 모든 경고를 오류로 승격.error로 특정 경고를 오류로 승격하고,--warn-error-options플래그로 선택적으로 다른 경고가 오류로 취급되지 않도록 제외.warn은 경고를 계속 경고로 취급하라고 dbt에 알려줘요.--warn-error-options플래그로silence를 사용해 경고 무시.
다음 예시에서는 dbt_project.yml 파일에서 NoNodesForSelectionCriteria 경고를 silence 매개변수에 추가해 무시하고 있어요:
dbt_project.yml
...
flags:
warn_error_options:
error: # Previously called "include"
warn: # Previously called "exclude"
silence: # To silence or ignore warnings
- NoNodesForSelectionCriteria
예시 (Examples)
여기서는 flags 또는 파일 기반 구성으로 warn_error_options를 구성하는 예시를 보여드릴게요.
특정 경고 대상으로 (Target specific warnings)
일부 예시는 --select 플래그가 dbt 프로젝트의 어떤 노드/리소스와도 일치하지 않을 때 발생하는 특정 경고 NoNodesForSelectionCriteria를 사용해요:
NoNodesForSelectionCriteria를 제외하고 모든 경고를 오류로 승격하는 명령:
dbt run --warn-error-options '{"error": "all", "warn": ["NoNodesForSelectionCriteria"]}'
deprecation 경고를 제외하고 모든 경고를 오류로 승격하는 명령:
dbt run --warn-error-options '{"error": "all", "warn": ["Deprecations"]}'
NoNodesForSelectionCriteria만 오류로 승격하는 명령:
dbt run --warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}'
환경 변수를 사용해 NoNodesForSelectionCriteria만 오류로 승격:
(dbt v1.11 이상)
DBT_ENGINE_WARN_ERROR_OPTIONS='{"error": ["NoNodesForSelectionCriteria"]}' dbt run
error, warn, silence 값은 배열로 전달해야 해요. 예를 들어 dbt run --warn-error-options '{"error": "all", "warn": ["NoNodesForSelectionCriteria"]}'가 맞고 dbt run --warn-error-options '{"error": "all", "warn": "NoNodesForSelectionCriteria"}'는 아니에요.
다음 예시는 dbt_project.yml 파일의 silence와 warn 매개변수를 사용해 NoNodesForSelectionCriteria 경고를 제외하고 모든 경고를 오류로 승격하는 방법을 보여줘요:
dbt_project.yml
...
flags:
warn_error_options:
error: all # Previously called "include"
warn: # Previously called "exclude"
- NoNodesForSelectionCriteria
silence: # To silence or ignore warnings
- NoNodesForSelectionCriteria
모든 경고를 오류로 승격
모든 경고를 오류로 승격하는 예시들:
dbt 명령 플래그 사용
dbt run --warn-error
dbt run --warn-error-options '{"error": "all"}'
dbt run --warn-error-options '{"error": "*"}'
환경 변수 사용
(dbt v1.11 이상)
WARN_ERROR=true dbt run
DBT_ENGINE_WARN_ERROR_OPTIONS='{"error": "all"}' dbt run
DBT_ENGINE_WARN_ERROR_OPTIONS='{"error": "*"}' dbt run
주의 —
warn_error_options: error: "all"을 사용하면 현재와 미래의 모든 경고가 오류로 취급돼요. 즉, 향후 dbt 버전에서 새 경고가 도입되면 프로덕션 작업이 예기치 않게 실패할 수 있어요. 프로덕션 환경에서는 주의해서 진행하고, 오류로 취급할 경고만 명시적으로 나열하기를 권장해요.
(dbt v2.0 이상) dbt v2 동작과 경고 코드
dbt v2는 warn_error_options를 완전히 지원해요. 이 섹션은 dbt v1 동작과의 중요한 차이를 설명해요. 기존 dbt-core 이벤트 이름은 세 가지 범주로 나뉘어요:
- 지원됨 (Supported): 유사한 dbt v2 경고에 매핑되어 대략 동일하게 동작해요.
- 지원되지 않을 예정 (Won't be supported): 우리가 의도적으로 지원하지 않기로 결정한 것들.
- 아직 지원되지 않음 (Not supported yet): 파싱되지만 아직 아무것도 하지 않아요.
dbt v2의 경고 코드
dbt v2에서 모든 경고는 숫자 코드(예: 1092)와 이벤트 이름(예: NoNodesForSelectionCriteria)을 모두 가져요. 런타임 경고 메시지는 둘 다 표시하지만, warn_error_options는 코드가 아니라 이름만 받아요:
flags:
warn_error_options:
error:
- NothingToDo # by name
silence:
- FreshnessConfigProblem # by name
지원되는 레거시 이벤트 이름, v2 네이티브 이름, 또는 지원되는 그룹(all, *)이 아닌 값(숫자 코드 포함)은 dbt v2가 시작 시 오류로 종료하게 해요. 예를 들어 {error: [1092]}는 실패하지만 {error: [NoNodesForSelectionCriteria]}는 동작해요. 이 페이지의 표에 모든 유효한 이름이 나타나는 것은 아니에요. dbt v2는 여기에 나열되지 않은 자체 경고(예: SemanticModelDeprecated, 코드 dbt1157)도 내보내요. 런타임 메시지에 표시된 이름을 사용하세요.
지원되는 레거시 dbt-core 이벤트 이름 별칭
로그에서 경고 코드를 보면 다음 표를 사용해 warn_error_options에 넣을 일치하는 이벤트 이름을 찾아요. code 열은 런타임에서 보는 경고를 조회하기 위한 것뿐이에요 — 구성에 코드 자체는 사용할 수 없어요:
| dbt v2 code (runtime only) | dbt-core event name (use this in config) | Description |
|---|---|---|
| 1601 | NoNodesSelected | No nodes selected |
| 1601 | NothingToDo | No nodes selected (alias) |
| 1087 | NodeNotFoundOrDisabled | A test or exposure dependency references a missing or disabled node |
| 1085 | DeprecatedModel | A model has passed its deprecation date and should be removed |
| 1072 | DeprecatedReference | A reference to a model that has already been deprecated |
| 1073 | UpcomingReferenceDeprecation | A reference to a model that will be deprecated on a future date |
| 1074 | JinjaLogWarning | Jinja exceptions.warn() called in a macro |
| 1075 | SnapshotTimestampWarning | Snapshot timestamp column type mismatch |
| 1076 | PackageRedirectDeprecation | A package has been redirected to a new name; update your packages.yml |
| 1077 | DepsUnpinned | A git-sourced package uses an unpinned revision (HEAD, main, or master) |
| 1078 | FreshnessConfigProblem | A source has no freshness configuration; freshness check was skipped |
| 1084 | WarnStateTargetEqual | The --state and --target directories are the same path |
| 1086 | WEOIncludeExcludeDeprecation | Deprecated include/exclude keys were used in warn_error_options; use error/warn instead |
| 1089 | NoNodeForYamlKey | A YAML key references a node that doesn't exist in the project |
| 1090 | MacroNotFoundForPatch | A patches: entry in a YAML file references a macro that doesn't exist |
| 1091 | InvalidConcurrentBatchesConfig | concurrent_batches is configured but not supported for this model |
| 1092 | NoNodesForSelectionCriteria | --select criteria matched no nodes |
| 1093 | MicrobatchModelNoEventTimeInputs | A microbatch model has no upstream inputs with event_time configured |
| 1094 | UnversionedBreakingChange | A breaking change was made to an unversioned model |
| 1095 | UnsupportedConstraintMaterialization | A constraint was defined on a materialization that doesn't support it |
| 1097 | UnusedResourceConfigPath | A +config path in dbt_project.yml doesn't match any resources |
| 1098 | DepsScrubbedPackageName | A package name contained characters that were scrubbed during install |
| 1099 | DepsFoundDuplicatePackage | The same package was found more than once in packages.yml |
| 1506 | InvalidMacroAnnotation | A macro's YAML annotation (argument name or type) doesn't match its Jinja definition |
| no code | LogTestResult | A data test result (pass/warn/fail) |
| no code | RunResultWarning | A model or test run completed with warn status |
| no code | RunResultWarningMessage | The message accompanying a warn-status run result |
지원되지 않는 dbt v1 이벤트 이름
Supported legacy dbt-Core event name aliases의 레거시 이름만 dbt v2에서 유효한 문자열 별칭이에요. 다른 많은 dbt v1 경고 이벤트 이름이 있으며, 그중 하나를 warn_error_options에 넣으면 dbt v2가 시작 시 경고를 던져요. 아래 표는 지원되지 않는 이름의 완전한 목록이 아니에요. dbt v2가 이름으로 인식해서 해당 항목이 효과가 없는 이유를 설명하는 시작 경고를 내보내 제거하도록 유도하는 dbt v1 이벤트 이름만 포함해요: 기본 dbt v1 동작이 dbt v2에서 제거되거나, 대체되거나, 무조건적이 되었기 때문이에요. 여기에 나열되지 않은 지원되지 않는 dbt v1 이름도 많으며, warn_error_options에 사용하면 시작 검증 중 여전히 경고를 내보내요.
| dbt-core event name | Message |
|---|---|
| MicrobatchMacroOutsideOfBatchesDeprecation | dbt v2 only supports the newer behavior-change flag, where this case is a hard error. |
| SeedExceedsLimitSamePath | This warning comes from partial parsing in dbt v1, which dbt v2 does not support. |
| SeedIncreased | This warning comes from partial parsing in dbt v1, which dbt v2 does not support. |
| GenerateSchemaNameNullValueDeprecation | dbt v2 only supports the newer behavior-change flag, where this case is a hard error. |
| GenericSemanticLayerDeprecation | dbt v2 already implements the new semantic layer spec, so this legacy warning no longer applies. |
| MFCumulativeTypeParamsDeprecation | dbt v2 already implements the new semantic layer spec, so this legacy warning no longer applies. |
| MFTimespineWithoutYamlConfigurationDeprecation | dbt v2 already implements the new semantic layer spec, so this legacy warning no longer applies. |
| MetricAttributesRenamed | dbt v2 already implements the new semantic layer spec, so this legacy warning no longer applies. |
| TimeDimensionsRequireGranularityDeprecation | dbt v2 already implements the new semantic layer spec, so this legacy warning no longer applies. |
| SourceFreshnessProjectHooksNotRun | dbt v2 already uses the newer source freshness behavior, so this legacy warning does not apply. |
| SemanticValidationFailure | dbt v2 does not support semantic models, so this warning does not apply. |
| ValidationWarning | dbt v2 already validates allowed YAML keys strictly, so this warning would be redundant. |
| PackageMaterializationOverrideDeprecation | dbt v2 already enforces the latest behavior, which prevents packages from overriding built-in materializations. |
| TestsConfigDeprecation | dbt v2 does not surface this warning by default, which matches current dbt v1 behavior. |
| ProjectFlagsMovedDeprecation | dbt v2 already errors on this configuration, which matches newer dbt v1 behavior. |
| ConfigSourcePathDeprecation | This is now fully deprecated in dbt v2. |
| ConfigLogPathDeprecation | This is now fully deprecated in dbt v2. |
| ConfigTargetPathDeprecation | This is now fully deprecated in dbt v2. |
| ConfigDataPathDeprecation | This is now fully deprecated in dbt v2. |
| EnvironmentVariableNamespaceDeprecation | dbt v2 reserves the DBT_ENGINE_ prefix and rejects unknown environment variables that use it. |
| UnusedTables | dbt v2 does not allow source overrides, so packages must disable a source explicitly instead. |
| WrongResourceSchemaFile | dbt v2 reports this case under NoNodeForYamlKey instead. |
| PackageNodeDependsOnRootProjectNode | dbt v2 only supports the newer behavior-change flag require_ref_searches_node_package_before_root, where this case is a hard error. |
dbt v2에서 하드 오류인 경고
일부 dbt v1 경고 이름은 dbt v2가 파싱 오류로 무조건 강제하는 동작에 해당해요. 이 이름들을 warn_error_options에서 참조하면 dbt v2는 항목이 효과가 없다는 시작 경고를 내보내요. dbt v1에서 warn_error_options 구성을 깨지 않고 그대로 가져올 수 있지만, 이 구성들은 아무것도 하지 않아요(지원되지 않는 것으로 경고를 던지고 구성에서 제거해야 해요):
| dbt-Core event name | dbt v2 behavior | dbt v2 error code |
|---|---|---|
| DuplicateYAMLKeysDeprecation | dbt v2's YAML parser rejects duplicate keys as hard parse errors | DuplicateConfigKey (1059) |
| CustomKeyInConfigDeprecation | Unknown config keys are rejected via strict schema validation | UnusedConfigKey (1060) |
| CustomTopLevelKeyDeprecation | Unknown top-level schema keys are hard parse errors | UnusedConfigKey (1060) |
| ResourceNamesWithSpacesDeprecation | Resource names with spaces are rejected during name validation | SchemaError |
| InvalidValueForField | Field value failures are surfaced as hard parse errors via deserialization | SerializationError |
| GenericJSONSchemaValidationDeprecation | JSON schema validation failures are hard parse errors | SerializationError |
| DuplicateNameDistinctNodeTypesDeprecation | Caught as a hard error during node resolution | SchemaError |
baseline 모드에서 --warn-error를 정적 분석과 함께 활성화
프로젝트가 정적 분석 경고를 내보내고 --warn-error(모든 경고를 오류로 승격)를 사용하면 프로젝트가 예기치 않게 실패할 수 있어요. baseline 모드가 활성화되어 있을 때는 error: all보다는 강제할 경고 범주를 명시적으로 나열하기를 권장해요.
Deprecated include와 exclude 키
warn_error_options의 레거시 include와 exclude 필드는 dbt v1.8에서 deprecated 되었지만 dbt v2에서는 여전히 지원돼요. 사용하면 dbt v2는 WEOIncludeExcludeDeprecation 경고(코드 1086)를 내보내고 deprecated 키를 무시해요. 대신 error, warn, silence로 마이그레이션하세요:
# Before (dbt ≤1.7)
flags:
warn_error_options:
include: all
exclude:
- NoNodesForSelectionCriteria
# After (dbt ≥1.8 and v2)
flags:
warn_error_options:
error: all
warn:
- NoNodesForSelectionCriteria
더 알아보기 (Learn more)
- About global configs — 전역 구성
- dbt v2 업그레이드 가이드 — 경고 코드 및 텔레메트리