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

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.

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)

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.