Diagnosing Command-Line Errors
A practical guide to interpreting command-line errors and troubleshooting carefully.
Read the Clues, Then Troubleshoot Safely
Treat errors as clues
An error message points toward a part of the operation to inspect; it does not always identify the cause by itself. Exact wording varies by program and system. Check the command, its arguments, the target path, your current location, and relevant permissions before deciding what to change.
| Message or symptom | What to check |
|---|---|
| `command not found` | Check spelling, installation, and the command search path. Bash commonly returns status `127` when it cannot find a command. |
| `No such file or directory` | Check the current directory, path spelling and capitalization, and whether the file or a parent directory exists. |
| `Permission denied` | Check whether you have permission to read, write, or execute the target; do not assume elevated privileges are the right fix. |
| `Is a directory` or `not a regular file` | Check whether a command expecting a file received a directory, or needs an option to process directories. |
| Too many arguments or unexpected extra files | Check whether an unquoted wildcard expanded or spaces in a path split it into multiple arguments. |
| No output | The command may have succeeded silently, found no matches, or sent an explanation to standard error. Check status and documented behavior. |
Troubleshoot in small, verifiable steps
Pause and establish context:
pwdshows the current directory, andls -lalists files there.Read the full command and output. Look for misspelled paths, missing arguments, misplaced options, or a difference between standard output and error messages.
In Bash, check
$?immediately after the command. Interpret the status according to that command, not as a universal explanation; a pipeline can also hide an earlier failure.Where possible, inspect or list a target before changing it. Change one thing at a time, rerun the command, and confirm that it did what you intended. For paths, quoting keeps spaces together; preview wildcard matches before using them with commands that change files.
Treat deletion as consequential. An interactive option may add a confirmation step, but it does not make deletion harmless. Do not guess by adding sudo, a force option such as -f, or recursive deletion: these can increase the impact of a mistake.