air-verse/air · error

failed to create a new configuration: %w

Error message

failed to create a new configuration: %w

What it means

After confirming `.air.toml` does not exist, writeDefaultConfig creates it with os.Create; if creation fails (permission, read-only filesystem, path is a directory), the error is wrapped as 'failed to create a new configuration'. The underlying cause is preserved via %w.

Source

Thrown at runner/config.go:355

	if err = applyPlatformOverrides(ret); err != nil {
		return nil, false, err
	}
	return ret, fromFile, nil
}

func writeDefaultConfig() (string, error) {
	fstat, err := os.Stat(dftTOML)
	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)
	}

View on GitHub (pinned to 71ea1dee05)

Solutions

1. Ensure the directory is writable: chmod/chown or move to another directory
2. Check that `.air.toml` is not a directory: `ls -la .air.toml`
3. Check disk space with `df -h`

Example fix

// before
air init  # failed to create a new configuration: is a directory
// after
rm -rf .air.toml   # remove the stray directory
air init

# ensure no .air.toml exists and the dir is writable before init
[ -e .air.toml ] && echo ".air.toml already exists"
[ -w . ] || echo "directory not writable"

if _, err := air.Init(); err != nil {
    if strings.Contains(err.Error(), "failed to create a new configuration") {
        log.Fatalf("cannot create .air.toml here: %v", errors.Unwrap(err))
    }
}

When it happens

Trigger: Running `air init` where a directory named `.air.toml` exists, the working directory is read-only, or the user lacks write permission.

Common situations: CI containers with read-only source mounts; running air init inside a directory where `.air.toml` is a directory; disk full.

Related errors

• failed to check for existing configuration: %w
• failed to write to %s: %w
• configuration already exists
• failed to marshal the default configuration: %w
• entrypoint values must be strings, got %T

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