air-verse/air · error

refusing to run in - this would watch too many files…

Error message

refusing to run in %s - this would watch too many files. Please run air in a project directory

What it means

Air refuses to start when the project root is a dangerous directory (like / or $HOME) where recursive file watching would be prohibitively expensive. The isDangerousRoot check detects these, and this error aborts startup unless Build.IgnoreDangerousRootDir is explicitly true.

Solutions

1. cd into your actual project directory before running air
2. Set `ignore_dangerous_root_dir = true` under [build] in .air.toml if you really intend this (with tighter exclude rules)
3. Restrict `include_dir`/`include_ext` in the config to narrow what gets watched
4. Run air inside the mounted project path in containers instead of the mount root

Example fix

// before (.air.toml, run in /home/user)
// air exits with this error
// after
[build]
ignore_dangerous_root_dir = true
exclude_dir = ["Documents", ".cache"]

// before running air
dir, _ := os.Getwd()
for _, bad := range []string{"/", os.Getenv("HOME")} {
	if dir == bad {
		return fmt.Errorf("refusing to run air in %s; cd into your project", dir)
	}
}

if err := air.Run(); err != nil && strings.Contains(err.Error(), "refusing to run in") {
	log.Fatalf("cd into a project directory first: %v", err)
}

When it happens

Trigger: Running `air` with its working directory (c.Root) at /, the user home directory, or similar; the config validation in config.go hits this before the watcher starts, unless `ignore_dangerous_root_dir = true` is set in [build].

Common situations: Launching air from a shell whose cwd is $HOME or / (forgot to cd into the project); Docker/CI setups mounting the repo at the container root; running air without a config in a too-broad directory.

Related errors

• build.rules[ ] ( ): at least one of include_dir…
• build.rules[ ] ( ): cmd is required
• build.rules[ ] ( ): failed to compile regex
• configuration already exists
• entrypoint must be a string or array of strings, got %T

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

Appendix: source

Thrown at runner/config.go:654

	if args != nil {
		c.withArgs(args)
	}
	cwd := os.Getenv(airWd)
	if cwd != "" {
		if err = os.Chdir(cwd); err != nil {
			return err
		}
		c.Root = cwd
	}
	c.Root, err = expandPath(c.Root)
	if err != nil {
		return err
	}

	// Check for dangerous root directories that could cause excessive file watching
	if isDangerous, dirName := isDangerousRoot(c.Root); isDangerous {
		if !c.Build.IgnoreDangerousRootDir {
			return fmt.Errorf("refusing to run in %s - this would watch too many files. Please run air in a project directory", dirName)
		}
		warnf("[warning] ignoring root directory protections. This could cause excessive file watching. It is recommended to run air in a project directory")
	}

	if c.TmpDir == "" {
		c.TmpDir = "tmp"
	}
	if c.TestDataDir == "" {
		c.TestDataDir = "testdata"
	}
	c.adjustDefaultsForTmpDir()
	ed := c.Build.ExcludeDir
	for i := range ed {
		ed[i] = cleanPath(ed[i])
	}

	if len(c.Build.Entrypoint) > 0 {
		entry := c.Build.Entrypoint.binary()

View on GitHub (pinned to 71ea1dee05)