air-verse/air · error

refusing to run in %s - this would watch too many files. Ple

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.

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)

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

• 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/3197dc2bd66d5bd1. Report an issue: GitHub.