air-verse/air · error

failed to check for existing configuration: %w

Error message

failed to check for existing configuration: %w

What it means

writeDefaultConfig first stats `.air.toml` to see whether a config exists; if Stat fails for a reason other than NotExist (e.g. permission denied on the directory), it returns this wrapped error instead of proceeding. It is distinct from the 'already exists' case — here the check itself failed.

Source

Thrown at runner/config.go:347

		// So need use this to avoid that none-zero slice will be overwritten.
		// https://dario.cat/mergo#transformers
		config.Transformers = sliceTransformer{}
		config.Overwrite = true
	})
	if err != nil {
		return nil, false, err
	}

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

View on GitHub (pinned to 71ea1dee05)

Solutions

1. Check permissions on the current directory: `ls -ld .` and fix with chmod/chown
2. Inspect the wrapped error (%w) to see the exact syscall cause
3. Run in a writable directory or as a user with access

Example fix

// before
air init  # failed to check for existing configuration: permission denied
// after
ls -ld .
chmod u+rwx .
air init

# verify the working directory is readable before air init
ls -la . >/dev/null || echo "cannot access directory"

if _, err := air.Init(); err != nil {
    if strings.Contains(err.Error(), "failed to check for existing configuration") {
        // stat failed — inspect unwrapped cause with errors.Unwrap
        log.Fatalf("config stat failed: %v", errors.Unwrap(err))
    }
}

When it happens

Trigger: Running `air init` in a directory where statting `.air.toml` fails with EACCES/EIO — e.g. a parent directory without execute permission, or `.air.toml` being a broken path with odd permissions.

Common situations: Read-only or restricted working directories (containers, mounted volumes); a `.air.toml` symlink pointing somewhere inaccessible; SELinux/AppArmor denials.

Related errors

• failed to create a new 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/cdb491b986af114f. Report an issue: GitHub.