plandex-ai/plandex · error

cannot process directory %s: requires --recursive/-r, --tree

Error message

cannot process directory %s: requires --recursive/-r, --tree, or --map flag

What it means

ParseInputPaths rejects a directory argument when none of the flags that legitimize directory loading (--recursive/-r, --tree, or --map) is set. The library refuses to guess how to expand a directory into context, so it fails fast with this message naming the directory.

Source

Thrown at app/cli/lib/context_paths.go:45

		for _, p := range fileOrDirPaths {
			var err error
			found, err = fs.IsSubpathOf(p, path, baseDir)
			if err != nil {
				return nil, fmt.Errorf("error checking if %s is a subpath of %s: %s", path, p, err)
			}
			if found {
				break
			}
		}

		if !found {
			continue
		}

		if projectPaths.AllDirs[path] {
			if !(loadParams.Recursive || loadParams.NamesOnly || loadParams.DefsOnly) {
				// log.Println("path", path, "info.Name()", info.Name())
				return nil, fmt.Errorf("cannot process directory %s: requires --recursive/-r, --tree, or --map flag", path)
			}

			// calculate directory depth from base
			// depth := strings.Count(path[len(p):], string(filepath.Separator))
			// if params.MaxDepth != -1 && depth > params.MaxDepth {
			// 	return filepath.SkipDir
			// }

			if loadParams.NamesOnly {
				// add directory name to results
				resPaths = append(resPaths, path)
			}
		} else {
			// add file path to results
			resPaths = append(resPaths, path)
		}
	}

View on GitHub (pinned to e2d772072e)

Solutions

1. Re-run with --recursive/-r to load the whole directory tree
2. Or use --tree / --map if a structural map of the directory is what you want
3. Or pass individual files instead of the directory

Example fix

// before
plandex context add src/
// after
plandex context add src/ --recursive

info, err := os.Stat(p)
if err == nil && info.IsDir() {
    if !recursive && !tree && !mapFlag {
        return fmt.Errorf("directory %s needs one of: -r, --tree, --map", p)
    }
}

func isDirectoryNeedingFlag(p string, params LoadParams, allDirs map[string]bool) bool {
    return allDirs[p] && !(params.Recursive || params.NamesOnly || params.DefsOnly)
}

paths, err := ParseInputPaths(args, baseDir, params)
if err != nil {
    if strings.HasPrefix(err.Error(), "cannot process directory") {
        fmt.Println("tip: add --recursive (-r), --tree, or --map for directories")
        os.Exit(2)
    }
    return err
}

When it happens

Trigger: Calling context load / MustLoadContext with projectPaths.AllDirs[path] true for a supplied path while loadParams.Recursive, loadParams.NamesOnly, and loadParams.DefsOnly are all false — e.g. `plandex context add src/` without -r.

Common situations: User passes a directory expecting it to be loaded wholesale; changed CLI defaults in a newer version; scripts that previously passed files now receive directory globs.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• invalid context index: %s
• no context found with name: %s
• invalid value for --debug: %v
• --debug value must be greater than 0
• run command requires exactly one file path argument

AI-assisted analysis of plandex-ai/plandex@e2d772072e (2026-09-05). Data as JSON: /api/errors/260faa178e8f13e9. Report an issue: GitHub.