air-verse/air · error

build.rules[%d] (%s): cmd is required

Error message

build.rules[%d] (%s): cmd is required

What it means

Config validation (normalizeRules) requires every entry in `build.rules` to define a `cmd`; a rule with an empty `cmd` fails validation with its index and name. Rules without cmd cannot run anything when their file matches.

Source

Thrown at runner/config.go:177

	regexCompiled []*regexp.Regexp
	includeDirAbs []string
}

func (r *cfgRule) delay() time.Duration {
	if r.Delay <= 0 {
		return 1000 * time.Millisecond
	}
	return time.Duration(r.Delay) * time.Millisecond
}

func (c *cfgBuild) normalizeRules(root string) error {
	for i := range c.Rules {
		r := &c.Rules[i]
		if r.Name == "" {
			r.Name = fmt.Sprintf("rule-%d", i)
		}
		if r.Cmd == "" {
			return fmt.Errorf("build.rules[%d] (%s): cmd is required", i, r.Name)
		}
		if len(r.IncludeDir) == 0 && len(r.IncludeExt) == 0 && len(r.IncludeFile) == 0 {
			return fmt.Errorf("build.rules[%d] (%s): at least one of include_dir, include_ext or include_file is required", i, r.Name)
		}
		r.includeDirAbs = r.includeDirAbs[:0]
		for _, dir := range r.IncludeDir {
			dir = cleanPath(dir)
			if dir == "" {
				continue
			}
			abs := filepath.Clean(dir)
			if !filepath.IsAbs(abs) {
				abs = filepath.Join(root, abs)
			}
			r.includeDirAbs = append(r.includeDirAbs, filepath.Clean(abs))
		}
		r.regexCompiled = r.regexCompiled[:0]
		for _, expr := range r.ExcludeRegex {

View on GitHub (pinned to 71ea1dee05)

Solutions

1. Add a cmd to the rule: cmd = "make generate"
2. Remove the empty [[build.rules]] block if unused
3. Give the rule an explicit name too, so future errors point at it

Example fix

// before (.air.toml)
[[build.rules]]
name = "codegen"
include_ext = ["go"]
// after (.air.toml)
[[build.rules]]
name = "codegen"
cmd = "go generate ./..."
include_ext = ["go"]

# before starting air, check each rules block has cmd
grep -A5 '^\\[\\[build.rules\\]\\]' .air.toml | grep -q 'cmd =' || echo "rule missing cmd"

When it happens

Trigger: Loading a `.air.toml` whose `[[build.rules]]` block omits `cmd` or sets `cmd = ""`, during config initialization.

Common situations: Copy-pasting a rules example and deleting the cmd line; adding a rule placeholder intending to fill in cmd later; a TOML formatting mistake that leaves cmd unset.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• build.rules[%d] (%s): at least one of include_dir, include_e
• build.rules[%d] (%s): failed to compile regex %q: %w
• configuration already exists
• entrypoint values must be strings, got %T
• entrypoint must be a string or array of strings, got %T

AI-assisted analysis of air-verse/air@71ea1dee05 (2026-08-31). Data as JSON: /api/errors/6ff4787cc477b8a1. Report an issue: GitHub.