air-verse/air · error

failed to marshal the default configuration: %w

Error message

failed to marshal the default configuration: %w

What it means

writeDefaultConfig marshals the default config struct to TOML before writing; if toml.Marshal fails, the error is wrapped with this message. This is rare — it indicates the in-memory default config cannot be encoded, typically an unsupported type, not a user config problem.

Source

Thrown at runner/config.go:364

	if err != nil && !os.IsNotExist(err) {
		return "", fmt.Errorf("failed to check for existing configuration: %w", err)
	}
	if err == nil && fstat != nil {
		return "", errors.New("configuration already exists")
	}

	file, err := os.Create(dftTOML)
	if err != nil {
		return "", fmt.Errorf("failed to create a new configuration: %w", err)
	}
	defer file.Close()

	config := defaultConfigBase()
	setEntrypointFromBin(&config)
	addPlatformOverridesForInit(&config, runtime.GOOS)
	configFile, err := toml.Marshal(config)
	if err != nil {
		return "", fmt.Errorf("failed to marshal the default configuration: %w", err)
	}

	headers := []byte(schemaHeader + "\n\n")
	content := append(headers, configFile...)

	_, err = file.Write(content)
	if err != nil {
		return "", fmt.Errorf("failed to write to %s: %w", dftTOML, err)
	}

	return dftTOML, nil
}

// defaultPathConfig loads `.air.toml` or `.config/air.toml` when present.
// The bool is true when a config file was loaded, false when defaults are returned.
func defaultPathConfig() (*Config, bool, error) {
	// when path is blank, first find `.air.toml` in `air_wd` and current working directory or .config/air.toml, if not found, use defaults
	for _, name := range []string{dftTOML, cfgTOML} {

View on GitHub (pinned to 71ea1dee05)

Solutions

1. Reinstall/rebuild air from a clean checkout: `go install github.com/air-verse/air@latest`
2. Check the wrapped error for the offending field and report it upstream if reproducible
3. Verify you are not running a locally patched fork with a bad default config type

Example fix

// before
air version  # custom patched build
// after
go install github.com/air-verse/air@latest
air init

if _, err := air.Init(); err != nil {
    if strings.Contains(err.Error(), "failed to marshal the default configuration") {
        // marshal failures are internal — retry with a clean air build
        log.Fatalf("marshal failed: %v; reinstall air", err)
    }
}

When it happens

Trigger: toml.Marshal(config) returning an error while generating the default config in `air init`, e.g. after a code/regression change introduces a field the TOML encoder cannot serialize.

Common situations: Practically only seen with a broken air build or modified fork whose defaultConfigBase() produces unencodable values; end users should rarely hit this.

Related errors

• configuration already exists
• entrypoint values must be strings, got %T
• entrypoint must be a string or array of strings, got %T
• build.rules[%d] (%s): cmd is required
• build.rules[%d] (%s): at least one of include_dir, include_e

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