Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Current »

Exception codes and error messages for the Adobe PDF Library are listed in the AcroErr.h header file. You will find this in the product installation package, in the directory called /CPlusPlus/Include/Headers.

The Adobe PDF Library creates error messages using a macro defined in AcroErr.h (lines 291-316). The product provides each error code as a series of bit field values, concatenated together into a single larger number.

Interpreting error messages with the ASGetErrorString API

The Adobe PDF Library offers an API, ASGetErrorString, that translates error codes into error messages that are easy to read and prints them to a command line monitor.

const char *ASGetErrorString(ASErrorCode errorCode, char *buffer, ASTArraySize lenBuffer);

ASGetErrorString() has three parameters:

  • errorCode. The error number that you want to translate into an error message text string. You must pass to the function the full error code number created with the ErrBuildCode() macro, or a user-defined exception returned with ASRegisterErrorString().
  • buffer. The buffer where ASGetErrorString will write the text string ( char buffer[256]; ). Make sure that you memset this buffer to 0 before you call ASGetErrorString.
  • lenBuffer. The number of characters that the buffer can hold. You can pass ASGetErrorString() sizeof(buffer) here.

ASGetErrorString() returns a pointer to buffer, but this pointer does not by itself indicate that the function worked.  If the buffer was memset to 0, call strlen on the returned buffer to determine if the error code was valid.

For example, the following code will convert an error code into an error message string, and print that string to stderr:

  char buf[256];
  ASGetErrorString(ERRORCODE, buf, sizeof(buf));
  fprintf(stderr, "Error code: %ld, Error Message: %sn", ERRORCODE, buf);

The use of the ASGetErrorString API is demonstrated in the sample program APDFLDoc.cpp. Find this sample program in your Adobe PDF Library software installation package:


The samples found in this directory are called by other sample Library sample programs.

Translating the Adobe PDF Library error code manually

The Adobe PDF Library provides each error code as a series of bit field values, concatenated together into a single larger number. You can interpret the message by converting the decimal value that results into hexadecimal.  The hexadecimal number is always eight digits long.

Remember that each hexadecimal number is a single digit that represents one of 16 values, between 0 and 15.  Hexadecimal digits are 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F.

It is easier to read if you use a  decimal to hexadecimal code converter  utility to convert the error code to hex notation, and then parse the hex version of the error code. 

You can also use the Windows 10 calculator app.  

Open the calculator and click the   icon in the upper left corner.

Click Programmer.

Type in a value for Dec to convert it to Hex. Try typing 1073938471:

Note that if you have an error code that is eight digits, it might be hexadecimal already. 

What do these error numbers mean?

Consider this example.  The error code 1073938471 can be converted to hex code 40030027, as shown in the Windows Calculator screens above. You can then parse that hex code into four fields:


Severity Level.  The ERR_SEVERITY_MASK values are found at lines 152 to 179 AcroErr.h header file.

The width of the field is four bits, and the format is designed to allow for up to 16 possible Severity Levels (2 to the 4th power). The Adobe PDF Library provides five levels, but you can add your own custom Severity Levels to the header file if you like.

The Severity Levels include:

                               ErrNoError=0No error occurred

ErrWarning Display a warning

ErrSuppressableDisplay a message if the user has not suppressed errors

ErrSilentNever display a message

ErrAlways Always display a message, even if others are suppressed



System Number. The ERR_SYSTEM_MASK refers to internal systems within the Adobe PDF Library, or categories of the type of errors displayed. Adobe PDF Library provides 19 default System types, but provides room for up to 256, so you can add many more System types to your APDFL application.

The default error messages provided by the Library are found in lines 183-282 of the AcroErr.h header file, and are listed below.

ErrSysNone=0General errors and out of memory errors

ErrSysCos CosStore filter errors

ErrSysCosSyntaxCos syntax errors

ErrSysPDDocPDDoc and family, Page tree, outlines errors

ErrSysPDPagePDPage and family, thumbs, annotations errors

ErrSysPDModelGlobal PD errors

ErrSysAcroViewAcroView errors

ErrSysPagePage parsing and RIPping errors

ErrSysFontSvrFont Server errors

ErrSysRasterRasterizer errors

ErrSysASFileASFile I/O errors

ErrSysXtnMgrExtension Manager errors

ErrSysXtnNew error codes added by extensions

ErrSysMDSystemPlatform-specific system errors

ErrSysMDAppPlatform-specific application errors

ErrSysPDFXPDFX-specific errors

ErrSysPDFEditPDFEdit errors

ErrSysPDSEditPDSEdit (structure) errors

ErrSysPDMetadataXAP Metadata errors


Error Number. The ERR_ERROR_MASK code maps to the individual error message, such as "pdErrNeedPassword," which means that a required password is missing.

The error number refers to the position of the error message in the list of error messages for the System. In this example, error number 0027 would be the 27th message found under system number 3, Cos Syntax Errors. So each error number is unique.

The list of error masks begins in the AcroForms.h header file with /*General Errors*/ at line 318, and continues to the end of the file. These are the errors provided with the Adobe PDF Library. Note that Datalogics also created error messages that can be returned, related to the .NET or Java Interfaces, or .NET Core.

The AcroErr.h header file provides 22 different categories for error messages, with six of these categories specific to individual platforms, such as Windows errors and macOS errors. The rest of the error messages can apply to any platform.

The error messages can be generic, such as "bad parameter." Keep in mind that functions call other functions; it could be that a function that expected a dictionary was passed something else. Even though the initial parameters were valid, you could still see a bad parameter error appearing from a function deep in your system workflow.

NoteIf you have a question about an error message, please contact your Datalogics Support Representative.

Error code examples

Error code 1073741825


1Convert number to Hex4000 0001
2Count to the severity item4ErrAlways

Count to the system item


Count to error item


Error code  537067605


1Convert number to Hex2003 0555
2Count to the severity item2ErrSuppressable

Count to the system item


Count to error item

85 (hex 55 is decimal 85)cosSynErrBadCharInHexString

  • No labels