What causes "build.rules[%d] (%s): failed to compile regex %q: %w" in air-verse/air?

Fix the regex syntax reported in the wrapped error; test with regexp.Compile or play.golang.org

build.rules[%d] (%s): failed to compile regex %q: %w

Error message

build.rules[%d] (%s): failed to compile regex %q: %w

What it means

Each rule's exclude_regex entries are compiled with regexp.Compile during config normalization; an invalid Go regular expression aborts loading with the failing pattern and the underlying regex error wrapped via %w.

Source

Thrown at runner/config.go:198

			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 {
			re, err := regexp.Compile(expr)
			if err != nil {
				return fmt.Errorf("build.rules[%d] (%s): failed to compile regex %q: %w", i, r.Name, expr, err)
			}
			r.regexCompiled = append(r.regexCompiled, re)
		}
	}
	return nil
}

func (c *cfgBuild) normalizeIncludeDirs(root string) {
	c.includeDirAbs = c.includeDirAbs[:0]
	c.extraIncludeDirs = c.extraIncludeDirs[:0]
	if root == "" {
		return
	}
	for _, dir := range c.IncludeDir {
		dir = cleanPath(dir)
		if dir == "" {
			continue
		}

View on GitHub (pinned to 71ea1dee05)

Solutions

Fix the regex syntax reported in the wrapped error; test with regexp.Compile or play.golang.org
Replace unsupported constructs (lookaheads/backreferences) with RE2-compatible patterns
Escape backslashes properly in the TOML string

Example fix

// before (.air.toml)
exclude_regex = ["_test(?=\.go)$"]
// after (.air.toml)
exclude_regex = ["_test\.go$"]

Defensive patterns

Strategy: validation

Validate before calling

package main

import (
    "fmt"
    "regexp"
    "os"
)

func main() {
    for _, expr := range []string{"_test\\.go$"} { // patterns from .air.toml exclude_regex
        if _, err := regexp.Compile(expr); err != nil {
            fmt.Fprintf(os.Stderr, "invalid exclude_regex %q: %v\n", expr, err)
            os.Exit(1)
        }
    }
}

Prevention

Test exclude_regex patterns against Go's regexp (RE2) before adding them
Avoid lookaheads/lookbehinds and backreferences — RE2 does not support them
Escape backslashes correctly inside TOML strings

When it happens

Trigger: A `.air.toml` rule with exclude_regex containing invalid syntax, e.g. unbalanced parentheses `(foo`, a bad escape `\q`, or a stray `*`, when the config is loaded.

Common situations: Copying PCRE/JS-flavored regex not supported by Go's RE2 (e.g. lookaheads `(?=...)`, backreferences); hand-editing a pattern and dropping a bracket; escaping mistakes in TOML strings.

Related errors

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