Technology · PRACTICAL GUIDE
find says “paths must precede expression”? Prove shell expansion before rewriting the command
The error usually means the shell or a wrapper changed the argument list before find parsed it; it does not prove the starting path is wrong. Capture the exact argv, separate starting points from the expression, quote patterns for find, then retest zero, one and many matches before any destructive action.
The message means find could not keep a clean boundary between starting points and the expression it was asked to evaluate. It does not, by itself, prove that the directory before -name is wrong.
The highest-value evidence is the exact argument vector. Prove what the shell or wrapper handed to find, classify each token, and validate the repaired command across zero, one and many matches before restoring any action that changes files.
1. Preserve the exact command and the argv boundary
Record the shell, working directory, find version, exact command, exit status and full stderr. If a safe reproduction is possible, trace the wrapper or function and print each argument as a separate quoted item; do not copy secrets into logs or use eval to reconstruct a command.
The diagnostic is emitted after find receives its argument vector. A visually identical command can reach find differently through an interactive shell, script, alias, variable or build tool, so the displayed command alone is not enough.
2. Reproduce zero, one and many pathname matches
Create a harmless test directory and run the same pattern with zero, one and multiple matching names. An unquoted *.txt may remain one word in one shell configuration, expand to one pathname and appear to work, or expand to several pathnames that find interprets as extra starting points before the expression.
Quote or escape a pattern intended for find itself, such as '*.txt', so the shell passes one pattern token. Treat different unmatched-pattern behavior in Bash, zsh and other shells as evidence to record, not as permission to guess.
3. Classify every token as a starting point or expression
Write one row per received argument. Mark genuine starting paths first, then tests such as -name and actions such as -print. Check the documented arity of each primary; a token supplied where no value is accepted can be misread as another path or expression.
Do not fix the message by moving every unfamiliar token to the front. Verify whether it is a path, option, test operand, grouping token or action for the installed find implementation, and use -- only where that implementation documents it.
4. Preserve boundaries through variables and wrappers
In Bash, unquoted parameter expansion can undergo word splitting and pathname expansion. Prefer arrays for a command assembled from multiple arguments, quote scalar values that must stay one argument, and inspect aliases, shell functions, service wrappers and build-tool substitutions separately.
Never repair the command with eval or a single joined string. Those approaches parse data again, can change spaces and wildcard meaning, and can create an injection path. Pass an explicit argument array from the owner that launches find.
5. Prove the repair before destructive actions
First replace destructive actions with -print and verify the selected paths in the zero-, one- and many-match fixtures, including names with spaces and leading dashes. Confirm that the same argv reaches find from the real wrapper or scheduler.
Only then restore -delete, -exec or another mutating action with a narrow test set and a rollback plan. Accept the repair when the diagnostic is gone, the printed set is correct in every fixture, and no token changes role between the shell and find.
