Macro argument validation

validate_macro_args	dbt Latest	dbt Core
Introduced	2025.03	1.10.0
Matured (default → true)	Sep 1, 2026	—
Removed	—	—

Loading table...

dbt supports optional validation for macro arguments using the validate_macro_args flag. By default, this flag is set to false, which means that dbt won't validate the names or types of documented macro arguments.

In the past, dbt didn't enforce a standard vocabulary for the type field on macro arguments in YAML. Because of this, the type field was used for documentation only, and dbt didn't check that:

• the argument names matched those in your macro
• the argument types were valid or consistent with the macro's Jinja definition

Here's an example of a documented macro:

macros/filename.yml

macros:
  - name: <macro name>
    arguments:
      - name: <arg name>
        type: <string>

When you set the validate_macro_args flag to true, dbt will:

• Validate macro arguments during project parsing.
• Check that all argument names in your YAML match those in the macro definition.
• Raise warnings if the names or types don't match.
• Validate that the type values follow the supported format.
• If no arguments are documented in the YAML, infer them from the macro and include them in the manifest.json file.

 When does validation occur?

Macro argument validation runs during project parsing, not during macro execution. Any dbt command that parses the project will trigger validation if you enable the validate_macro_args flag.

• In dbt Core:
  • Validation runs as part of parsing for most commands (parse, build, run, test, seed, snapshot, compile).
  • With a full parse, dbt validates all macros.
  • With partial parsing (the default), dbt validates only macros affected by changed files.
  • Use --no-partial-parse to force validation of all macros.

Impact when the flag matures

On its own, the flag emits warnings and builds continue. However, these warnings use the force-handled path and respect --warn-error, so projects with --warn-error set will see build failures at parse time.

This affects projects where the arguments: listed in a macro's YAML patch no longer match the macro's actual Jinja signature. For those projects, every command fails at parse time until you either update the YAML arguments to match the macro or remove the arguments: block entirely.

 Recommended actions

If InvalidMacroAnnotation warnings are appearing at parse time (or causing parse failures with --warn-error set), check each log line — it names the macro and the specific mismatch. In the macros: YAML block for each affected macro, align the arguments: entries with the {% macro name(args) %} declaration in the .sql file, or remove the arguments: block entirely.

To silence the warnings without fixing the YAML, use warn_error_options:

dbt_project.yml

flags:
  warn_error_options:
    silence:
      - InvalidMacroAnnotation

To opt out of this behavior, set the flag to false:

dbt_project.yml

flags:
  validate_macro_args: false

Was this page helpful?

Privacy policyCreate a GitHub issue

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.