Linux › Section B · Basic commands and the directory hierarchy › Topic B.9

Understanding error messages

When something fails on Linux, the error message usually tells you exactly what went wrong and where. Learning to read it carefully, and to recognise the handful of errors you will meet again and again, turns most problems into quick fixes.

Read the message first

The most useful troubleshooting habit is also the simplest: read the whole error message before doing anything else. Unix programs are terse, but their messages are precise. Most of them come from a small, shared vocabulary, so once you know what No such file or directory or Permission denied really means, you can diagnose problems in programs you have never used before. Guessing, or retyping the command with random changes, wastes time and can make things worse. Copy the exact message into your notes or a search if you need to; the wording matters.

Anatomy of an error message

Take ls: cannot access '/nosuch': No such file or directory, printed by GNU ls. It has three parts. First comes the program that complained, ls. Next is the object it was working on, the path '/nosuch', which current GNU tools print in quotes. Last, after the final colon, is the reason. Read together: ls tried to access /nosuch and could not, because it does not exist. Inside a shell script the first part may name the script or the shell instead, as in bash: line 5: cd: a: Not a directory, which also tells you the line number to look at.

Where the reason comes from

Many reasons are not invented by the program at all. When a program asks the kernel to open, create or delete a file, the system call either succeeds or returns an error code with a symbolic name, such as ENOENT (error: no entry). The C library turns that code into the familiar text, so every program reports the same failure in the same words. Common pairs on Linux are EPERM (1) Operation not permitted, ENOENT (2) No such file or directory, EACCES (13) Permission denied, EEXIST (17) File exists, ENOTDIR (20) Not a directory, EISDIR (21) Is a directory and ENOSPC (28) No space left on device. The errno(3) manual page lists them all.

File and directory errors

No such file or directory is the most common error of all. It appears when a file is missing, when cd names a directory that is not there, or when you write into a directory that does not exist. Check spelling, case and your current directory. File exists means you tried to create something already present, as in mkdir: cannot create directory 'a': File exists, often because a file has the name you wanted for a directory. Not a directory means part of a path is an ordinary file being used as a directory; Is a directory means the reverse, as in cat: .: Is a directory. rmdir reports Directory not empty when the directory still has entries.

Permission and command errors

Permission denied (EACCES) means the file's permissions do not allow what you tried: reading, writing, or running a file without its execute bit, which Bash reports as bash: ./backup.sh: Permission denied. Operation not permitted (EPERM) means the action needs privileges you lack, such as signalling another user's process or changing a file you do not own. bash: name: command not found means no program of that name exists in any directory on your PATH. Bash gives a failed command an exit status too: 127 for command not found and 126 for a command that cannot be run, as the topic Special variables and exit codes explains.

Full disks and crashed programs

No space left on device means a filesystem is full; df -h shows each filesystem's free space. It can also appear when space remains but the filesystem has run out of inodes, the records that describe files, which df -i reveals; Inside a traditional filesystem: inodes and links explains them. A program that ends with Segmentation fault has tried to touch memory it was not allowed to use, so the kernel stopped it with the SIGSEGV signal. Bus error means a similar invalid memory access. Both point to a bug in the program, unexpected input, or occasionally faulty memory, not to a mistake in your command line.

Worked example: following a path

In a test directory, you run touch a, which creates an empty file, then touch a/b. The response is touch: cannot touch 'a/b': Not a directory. 1. Program: touch. 2. Object: the path a/b. 3. Reason: Not a directory. 4. Apply the reason to the path: b cannot be created inside a, because a is a regular file, not a directory. 5. Confirm with ls -l a, whose first character is - for a regular file rather than d. 6. Fix: choose another name for the directory, or remove the file and run mkdir a. The error names the whole path, but the problem lies with one component, so test each component in turn.

Worked example: where access stops

A user gets cat: /srv/app/config.yml: Permission denied, although the file itself is readable by everyone. 1. The reason is EACCES, so think about permissions, not existence. 2. Access needs execute permission on every directory along the path, not just read permission on the file. 3. Run namei -l /srv/app/config.yml, from util-linux, which lists each component with its mode. 4. Illustrative output shows drwxr-xr-x for / and srv, then drwx------ app app for app, and -rw-r--r-- for config.yml. 5. The app directory admits only its owner, so access stops there. 6. The fix is to change that directory's permissions or groups, covered in File modes and permissions.

Work through problems methodically

Always deal with the first error first. Programs often print one real failure followed by a cascade of consequences: a daemon that cannot read its configuration file may then complain about every setting it is missing, and creating that one file fixes everything. Do not confuse warnings with errors: a line containing warning means the program noticed something odd but carried on. For harder problems, define exactly what fails and what changed recently, gather evidence from messages and logs, test one hypothesis at a time with the smallest safe change, and write down what fixed it.

Common mistakes to avoid

First, skimming past the message and changing the command at random. Second, fixing the last error in a long list instead of the first. Third, reading Permission denied as a missing file, or No such file or directory as a permissions problem: the reason text is specific. Fourth, blaming the final component of a path when an earlier directory is the real problem. Fifth, treating a warning as fatal, or ignoring it completely. Sixth, assuming a full disk when df -h shows free space: check df -i for inodes as well.

Key takeaways

Error messages usually give the program, the object and the reason, in that order. Many reasons come from kernel error codes: ENOENT No such file or directory, EEXIST File exists, ENOTDIR Not a directory, EISDIR Is a directory, EACCES Permission denied, EPERM Operation not permitted and ENOSPC No space left on device. command not found means nothing matched on the PATH. Segmentation fault and bus error mean a program made an invalid memory access. Fix the first error first, tell warnings from errors, use namei -l to see where a path is blocked, and check both df -h and df -i for full disks.

Flashcards

Flashcard

Program: object: reason

The usual three parts of a Unix error message

ls: cannot access '/x': No such file or directory

Test your understanding

Question 1 of 5

You run touch notes, then mkdir notes. What error do you expect?

Question 2 of 5

A program prints 40 lines of errors. The first says it cannot open /etc/app/app.conf: No such file or directory. What should you do first?

Question 3 of 5

Which message means you tried something that needs privileges, such as signalling another user's process?

Question 4 of 5

A server reports No space left on device, but df -h shows the filesystem only 40% full. What should you check next?

Question 5 of 5

What does bash: htop: command not found tell you?

← Previous topicNext topic →