Decode MariaDB and Linux error numbers with perror

You will turn a numeric error from MariaDB or a Linux-facing diagnostic into readable text with perror. The command only reports meanings: it does not retry a query, change permissions, restart a service or repair a database. Allow about five minutes for a single error and a little longer if you need to identify which error family produced the number.

You need a shell and the MariaDB client utilities. No database connection or elevated privilege is required. The examples below use the installed Ubuntu package mariadb-client version 1:10.11.14-0ubuntu0.24.04.1, whose executable reports MariaDB client version 2.11. Output wording and the meaning of system numbers can vary with the operating system and package release.

1. Check the installed command

Start by confirming which executable your shell will run and recording its version:

$ command -v perror
/usr/bin/perror
$ perror --version
perror Ver 2.11, for debian-linux-gnu (x86_64)

If command -v prints nothing, install or enable the MariaDB client package through your normal package-management process. Do not use sudo just to read an error number. If more than one client installation is present, the path from command -v tells you which one the shell selected.

2. Decode one or more Linux system errors

Give perror the number shown after text such as errno: or Errcode:. The normal verbose mode prints both the number and its message, and accepts several numbers in one invocation:

$ perror 13 64
OS error code  13:  Permission denied
OS error code  64:  Machine is not on the network

These are operating-system errors, not MariaDB-specific diagnoses. Error 13 commonly points towards a permission check, but it does not tell you which path, user or access mode failed. Return to the application or server log for that context. Error 64 describes the local system's interpretation of that number; do not assume the same number has the same meaning on a different operating system.

Use the exact number from the diagnostic. Guessing from a nearby number can send troubleshooting in the wrong direction.

3. Remove the prefix when another tool needs plain text

The --silent option, also available as -s, prints only each message. This is useful for a compact report or for feeding human-readable text into another command:

$ perror --silent 13 64
Permission denied
Machine is not on the network

Silent mode does not change the lookup. It only removes the error family and number from the displayed line. For an incident record, the default verbose output is usually safer because it preserves the number that was investigated.

4. Decode MariaDB error numbers

MariaDB server errors use a different number space from Linux errno values. perror recognises many of those numbers and prints the symbolic name, a message template and a link to MariaDB's error-code documentation:

$ perror 1064 1045 1146
MariaDB error code 1064 (ER_PARSE_ERROR): %s near '%-.80T' at line %d
Learn more: https://mariadb.com/kb/en/e1064/
MariaDB error code 1045 (ER_ACCESS_DENIED_ERROR): Access denied for user '%s'@'%s' (using password: %s)
Learn more: https://mariadb.com/kb/en/e1045/
MariaDB error code 1146 (ER_NO_SUCH_TABLE): Table '%-.192s.%-.192s' doesn't exist
Learn more: https://mariadb.com/kb/en/e1146/

The %s, %d and similar sequences are placeholders from the server's message template. They are not missing values that perror can fill in. Find the original server error, query text or application log if you need the actual table, user or line number.

Do not classify an arbitrary number by its size alone. Compare the surrounding text and the source log. A number that looks like a MariaDB error can instead be an operating-system error, and the same system number can have a different meaning elsewhere.

5. Check failure and option mistakes

A recognised lookup normally exits successfully, including when the message describes a problem such as permission denial. An invalid number is different:

$ perror 999999
Illegal error code: 999999
$ echo $?
1

Use the exit status to detect an invalid lookup in a script, but do not treat status zero as proof that the underlying database operation succeeded. perror is only a decoder; it does not test the condition that produced the number.

For a quick option reference, run:

$ perror --help

The installed command supports --help, --info and -? for help; --silent and -s; --verbose and -v; and --version and -V. Verbose output is the default. The help text also documents the end-of-options marker -- for negative error-code arguments. Treat negative values as a special case and preserve the exact command and output when reporting them, because option parsing is easy to misread.

6. Keep the investigation reversible

There is no state change to undo: perror reads its arguments and writes a message to standard output. It does not contact the MariaDB server, inspect a table, alter a file or require root access. That makes it safe to run against a production error number, but the result is still only a clue.

When a message suggests permissions, network reachability or a missing table, investigate that condition with the relevant tool and the original service context. Avoid "fixing" the decoded message by broadly changing file modes, firewall rules, credentials or schema. Those changes can create a second incident and are outside perror's job.