unsupported color mode

Error message

unsupported color mode: %s. Expected always, auto, or never

What it means

Air validates the `color.mode` config value and only accepts "always", "never", "auto", or empty. Any other string fails config validation and air exits with this message.

Solutions

Change color mode in .air.toml to one of: "always", "auto", or "never"
Use "auto" (or remove the key) to let air detect TTY support
Check casing — the value must be lowercase

Example fix

// before (.air.toml)
[color]
mode = "on"
// after
[color]
mode = "auto"

Defensive patterns

Strategy: validation

Validate before calling

// pre-validate color mode
switch colorMode {
case "", "auto", "always", "never":
	// ok
default:
	return fmt.Errorf("invalid color mode %q; use always|auto|never", colorMode)
}

Try / catch

if err := loadConfig(); err != nil && strings.Contains(err.Error(), "unsupported color mode") {
	log.Fatal("fix [color] mode in .air.toml: always, auto, or never")
}

Prevention

Only use documented enum values: always, auto, never
Values are case-sensitive and lowercase
Omit [color] entirely to get the auto default
Copy config snippets from air_example.toml, not other tools

When it happens

Trigger: Setting `[color] mode` in .air.toml to a misspelled or unsupported value such as "true", "yes", "on", or "Always" (case-sensitive check) — the switch statement falls through to the default branch.

Common situations: Copying a config from another tool that uses on/off/force vocabulary; typo like "alwyas"; wrong casing since the comparison is case-sensitive.

Related errors

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

Appendix: source

Thrown at runner/config.go:722

				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)
	}

	if len(c.Build.FullBin) > 0 {
		c.Build.Bin = c.Build.FullBin
		return err
	}
	// Fix windows CMD processor
	// CMD will not recognize relative path like ./tmp/server
	c.Build.Bin, err = filepath.Abs(c.Build.Bin)

	return err
}

// adjustDefaultsForTmpDir updates Build.Cmd, Build.Bin, and Build.ExcludeDir
// when they still hold their default values but TmpDir has been changed.
func (c *Config) adjustDefaultsForTmpDir() {
	c.adjustDefaultsForTmpDirWithOS(runtime.GOOS)
}

View on GitHub (pinned to 71ea1dee05)