What causes "failed to compile regex %q: %w" in air-verse/air?

Fix the pattern reported by %q so it is valid Go regexp (RE2) syntax

failed to compile regex %q: %w

Error message

failed to compile regex %q: %w

What it means

Air compiles each pattern in Build.ExcludeRegex into a *regexp.Regexp during config validation. If any pattern is not valid Go RE2 syntax, startup aborts with this error wrapping the regexp error.

Source

Thrown at runner/config.go:704

	}

	adaptToVariousPlatforms(c)
	c.Build.normalizeIncludeDirs(c.Root)
	if err = c.Build.normalizeRules(c.Root); err != nil {
		return err
	}

	// Join runtime arguments with the configuration arguments
	runtimeArgs := flag.Args()
	c.Build.ArgsBin = append(c.Build.ArgsBin, runtimeArgs...)

	// Compile the exclude regexes if there are any patterns in the config file
	if len(c.Build.ExcludeRegex) > 0 {
		regexCompiled := make([]*regexp.Regexp, len(c.Build.ExcludeRegex))
		for idx, expr := range c.Build.ExcludeRegex {
			re, err := regexp.Compile(expr)
			if err != nil {
				return fmt.Errorf("failed to compile regex %q: %w", expr, err)
			}
			regexCompiled[idx] = re
		}
		c.Build.regexCompiled = regexCompiled
	}

	c.Build.ExcludeDir = ed

	// Set colorful output, see https://github.com/fatih/color#disableenable-color
	switch c.Color.Mode {
	case "always":
		color.NoColor = false
	case "never":
		color.NoColor = true
	case "auto", "":
		break
	default:
		return fmt.Errorf("unsupported color mode: %s. Expected always, auto, or never", c.Color.Mode)

View on GitHub (pinned to 71ea1dee05)

Solutions

Fix the pattern reported by %q so it is valid Go regexp (RE2) syntax
Replace unsupported PCRE features (lookaheads, backreferences) with RE2-compatible alternatives
Test the pattern first with a small Go snippet or playground using regexp.Compile
Escape backslashes properly inside TOML literal strings (use single quotes: exclude_regex = ['\.foo$'])

Example fix

// before (.air.toml)
exclude_regex = ["(foo|bar"]
// after
exclude_regex = ["^(foo|bar)$"]

Defensive patterns

Strategy: validation

Validate before calling

// pre-validate exclude_regex entries
for _, expr := range excludeRegex {
	if _, err := regexp.Compile(expr); err != nil {
		return fmt.Errorf("bad exclude_regex %q: %w", expr, err)
	}
}

Try / catch

if err := cfg.Validate(); err != nil {
	if strings.Contains(err.Error(), "failed to compile regex") {
		log.Fatalf("fix exclude_regex pattern: %v", err)
	}
	log.Fatal(err)
}

Prevention

Test patterns with Go's regexp before adding them to config
Remember Go uses RE2: no lookaheads/lookbehinds/backreferences
Use TOML literal strings (single quotes) to avoid double-escaping backslashes
Keep patterns simple; prefer exclude_dir/exclude_file over regex where possible

When it happens

Trigger: Setting `exclude_regex` in .air.toml to a string with invalid regex syntax (unbalanced parenthesis/bracket, invalid escape like \d in wrong context, trailing backslash) — regexp.Compile fails and the error is returned.

Common situations: Porting PCRE-only constructs like lookaheads (?=...) or backreferences, which Go regexp does not support; escaping mistakes after TOML string processing; typos like `(foo|bar` with a missing close paren.

Related errors

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