When developing software, troubleshooting system daemons, or analyzing crash logs on macOS, developers and power users frequently encounter cryptic numeric error codes. Whether seeing a negative integer in an installer log (such as error -10810 or -50), a POSIX errno value in a terminal command failure, or an Open Directory failure code, identifying what the numbers actually signify usually requires digging through obscure Apple Developer header files. The macOS operating system includes a built-in diagnostic tool tailored specifically for this purpose: macerror. Located within the Xcode command-line developer tools, macerror instantly translates numeric error codes into human-readable constant names, subsystem origins, and descriptive explanations.
Understanding macOS Error Code Domains
Due to the historical evolution of macOS—combining the Mach microkernel, FreeBSD POSIX foundations, NeXTSTEP frameworks, and classic Mac OS Carbon APIs—error codes originate from several distinct software layers:
- POSIX Errno Codes: Standard Unix return codes (1 to 106), including
EPERM (1),ENOENT (2), andEACCES (13). - CoreServices and Carbon Errors: Negative four-to-five-digit integers originating from classic framework layers (such as
kPOSIXErrorBase, LaunchServices errors, or File Manager errors). - Mach Kernel Traps: Return codes from Mach messaging and virtual memory subsystems (such as
KERN_INVALID_ADDRESS (1)orKERN_PROTECTION_FAILURE (2)). - Security and Keychain Codes: Cryptographic and keychain status codes defined in
SecBase.h(such aserrSecItemNotFound (-25300)orerrSecAuthFailed (-25293)).
The macerror utility queries an internal dictionary compiled from Apple SDK system headers (including MacErrors.h and SecBase.h), delivering instantaneous translations from the terminal.
Verifying and Installing macerror
The macerror command is included as part of the Apple Command Line Tools package. To verify whether the tool is available on your Mac, open the Terminal application (found in /Applications/Utilities/Terminal.app) and execute:
which macerror
If the path /usr/bin/macerror is returned, the tool is installed and ready for use. If it is not found, install the official developer tools package by running:
xcode-select --install
A software update prompt will appear; click Install and follow the on-screen instructions.
Decoding Standard Negative Error Codes
To decode an error code, invoke macerror followed by the integer. Negative error codes can be passed with a leading hyphen or without.
For example, if an application fails to launch and emits error code -10810, translate it by running:
macerror -10810
The terminal immediately returns the system constant and description:
kLSUnknownErr = -10810, /* An unknown error has occurred in LaunchServices */
This confirms that the failure occurred inside the LaunchServices daemon, usually indicating that the app bundle structure is damaged or missing required execute permissions.
To inspect another common system failure, error -50:
macerror -50
The output reports:
paramErr = -50, /* error in user parameter list */
This indicates that a system call or file API received invalid or out-of-range parameters.
Decoding Hexadecimal Error Codes
Crash logs, console traces, and debugging tools like LLDB often format return codes in hexadecimal notation (such as 0x80000001 or 0xFFFF9D24).
You can pass hexadecimal values directly to macerror using the standard 0x prefix:
macerror 0xFFFF9D24
The utility evaluates the two’s complement integer equivalent and outputs the corresponding error definition.
Auditing Security and Keychain Errors
When debugging code signing, certificates, or Keychain access issues, you frequently encounter negative five-digit error codes starting with -25.
To diagnose a common Keychain lookup failure, error -25300:
macerror -25300
The output provides the exact Security framework constant:
errSecItemNotFound = -25300, /* The specified item could not be found in the keychain. */
If a code signing validation fails with error -67062:
macerror -67062
The tool outputs:
errSecCSBadCode = -67062, /* The code is invalid or has been corrupted. */
This directly points to corrupted Mach-O binary headers or invalid code signatures without needing to search online databases.
Decoding Multiple Error Codes Simultaneously
You can pass multiple error codes in a single command invocation to decode a batch of related errors encountered during an application crash sequence:
macerror -43 -50 -10810
The utility lists the decoded descriptions sequentially:
fnfErr = -43, /* File not found */
paramErr = -50, /* error in user parameter list */
kLSUnknownErr = -10810, /* An unknown error has occurred in LaunchServices */
Incorporating macerror into your terminal workflow eliminates guesswork when interpreting system crash dumps and installer logs, making macOS debugging fast, accurate, and self-contained.