Decode OpenSSL Error Codes with errstr

You will turn an OpenSSL hexadecimal error code into readable diagnostic text, then check that the lookup used the OpenSSL installation you intended. Allow about five minutes. You need a Linux shell and the openssl command; decoding an error does not require root, a service restart or a change to any file.

1. Confirm the command and version

errstr uses the error-code tables in the OpenSSL libraries that run with the command. The command found first in PATH therefore matters. On this machine, the packaged manpage describes OpenSSL 3.0.13 and /usr/bin/openssl is package version 3.0.13-0ubuntu3.15. A separate Homebrew installation is also earlier in PATH and reports OpenSSL 3.6.1. Use the absolute path when you need the packaged behaviour shown here.

$ command -v openssl
/home/linuxbrew/.linuxbrew/bin/openssl
$ type -a openssl
openssl is /home/linuxbrew/.linuxbrew/bin/openssl
openssl is /usr/bin/openssl
$ /usr/bin/openssl version
OpenSSL 3.0.13 30 Jan 2024 (Library: OpenSSL 3.0.13 30 Jan 2024)
$ dpkg-query -W -f='${Package} ${Version}\n' openssl
openssl 3.0.13-0ubuntu3.15

If command -v prints a different path, either use that installation consistently or replace /usr/bin/openssl in the examples with the path you have checked. Do not assume that a matching executable name means matching error tables.

Checkpoint: you know which binary produced the diagnostic and which OpenSSL version it uses.

2. Extract the hexadecimal code

An OpenSSL error may appear as a colon-separated line such as 27594:error:2006D080:lib(32)::reason(128)::107:. The manpage's rule is to use the hexadecimal digits after the second colon, so the lookup value is 2006D080. Do not pass the timestamp, the word error or the complete log line.

Keep the original diagnostic line. It provides context that errstr cannot recover, including where the error was logged and any later application text.

$ /usr/bin/openssl errstr 2006D080
error:2006D080:lib(64)::reason(446592)

The command prints the decoded form to standard output and exits successfully for this lookup. The numeric library and reason fields can differ from an older example in the manual because OpenSSL error tables and builds are version-specific. Treat the output from the exact executable you checked as authoritative for that host.

For an error whose reason text is present in this installation, the result is more useful:

$ /usr/bin/openssl errstr 10000080
error:10000080:BIO routines::no such file

This tells you that code 10000080 maps to the BIO routines' "no such file" reason in OpenSSL 3.0.13. It does not identify the missing path or fix the operation that produced the error. Return to the application log for that context.

3. Decode several codes in one run

The synopsis accepts one or more error codes. Pass each code as a separate shell argument. The output has one decoded line per argument, in the same order:

$ /usr/bin/openssl errstr 10000080 02001002
error:10000080:BIO routines::no such file
error:02001002:rsa routines::reason(4098)

Use a simple loop when a log has a short, trusted list of values. Keep each value quoted if it came from a variable, and validate the source before using a larger batch. This is a decoder, not a general log parser: it does not scan a file for codes automatically.

$ for code in 10000080 02001002; do
>   /usr/bin/openssl errstr "$code"
> done
error:10000080:BIO routines::no such file
error:02001002:rsa routines::reason(4098)

Checkpoint: every output line corresponds to one input argument, and the binary path is still the one you verified.

4. Check the option syntax

The only documented option for this command is -help. It prints usage information and the errnum... parameter description. It does not decode a value itself.

$ /usr/bin/openssl errstr -help
Usage: errstr [options] errnum...

General options:
 -help     Display this summary

Parameters:
 errnum    Error number(s) to decode

Do not add a guessed option to change the output format. If a script needs structured data, capture the plain output and parse only after pinning the OpenSSL version, because the text and numeric fields are not a stable application interface.

5. Handle empty or invalid input

An empty invocation is a distraction trap. With the packaged OpenSSL 3.0.13 binary it produces no output and returns status 0, so a shell script must not use success alone to prove that a code was decoded. Check that a value was supplied before calling the command.

$ /usr/bin/openssl errstr
$ printf 'status: %s\n' "$?"
status: 0

An invalid non-numeric value behaves differently: this installation returns status 1 and produces no decoded line. Treat that as a bad input, not as evidence that the error code was unknown.

$ /usr/bin/openssl errstr not-a-code
$ printf 'status: %s\n' "$?"
status: 1

If a numeric code produces a generic result such as lib(64)::reason(446592), first check the binary and library version, then compare the original log with the code extraction rule. A generic result can be a valid lookup even when this build has no descriptive reason string for that value.