API Return Codes

Note: In some shell environments, return codes above 255 may be returned modulo 256. This can, in particular, cause service return codes (which range from 4000 upward) to be mistaken for (possibly) non-existent common STAF return codes. For example, if a service returned the return code 4010, this might appear to be the return code 170 (4010 modulo 256) in a shell environment.

Table 1. STAF API Return Codes

Error Code Meaning Comment
0 No error
1 Invalid API This indicates that a process has tried to call an invalid internal STAF API. If this error occurs, report it to the authors.
2 Unknown Service You have tried to submit a request to a service that is unknown to STAFProc. Verify that you have correctly registered the service.
3 Invalid Handle You are passing an invalid handle to a STAF API. Ensure that you are using the handle you received when you registered with STAF.
4 Handle already exists This indicates that you are trying to register a process with one name when that process has already been registered with a different name. If you register the same process multiple times, ensure that you use the same name on each registration call.
Note: If you receive this error code when trying to perform an operation other than registering a service, report it to the authors.
5 Handle does not exist You are trying to perform an operation on a handle that does not exist. For example, you may be trying to stop a process, but you are specifying the wrong handle.
6 Unknown Error An unknown error has occurred. This error is usually an indication of an internal STAF error. If this error occurs, report it the authors.
7 Invalid Request String You have submitted an improperly formatted request to a service. See the appropriate section in this document for the syntax of the service's requests, or contact the provider of the service.
Note: Additional information regarding the exact syntax error may be provided in the result passed back from the submit call.
8 Invalid Service Result This indicates an internal error with the service to which a request was submitted. If this error occurs, report it to the authors and the service provider.
9 Rexx Error This indicates an internal error in an external Rexx service. If this error occurs, report it to the authors and the service provider.
Note: The actual Rexx error code will be returned in the result passed back from the submit call.
10 Base OS Error This indicates that a base operating system error was encountered.
Note: The actual base operating system error code, and possibly additional information about the error, will be returned in the result passed back from the submit call.
11 Process Already Complete You are trying to perform an invalid operation on a process that has already completed. For example, you may be trying to stop the process or register for a process end notification.
12 Process Not Complete You are trying to free process information for a process that is still executing.
13 Variable Does Not Exist You are trying to get, remove, or resolve a variable that does not exist. Remember that variables are case sensitive. The name of the variable that does not exist will be in the result passed back from the submit call.
14 UnResolvable String You have requested to resolve a string that cannot be resolved. This indicates that you have exceeded the resolution depth of the VAR service. The most common cause of this is recursive variables definitions.
15 Invalid Resolve String The string you requested to be resolved has a non-matching left or right curly brace. Ensure that all variable references have both left and right curly braces.
16 No Path To Endpoint This indicates that STAFProc was not able to submit the request to the requested endpoint (i.e. target machine). This error usually indicates one or more of the following:

STAFProc is not running on the target machine.
The requested endpoint is not valid.
The network interface or port for the requested endpoint is not supported.
A firewall is blocking communication via the port for the requested endpoint.
A secure network interface is being used to communicate to a machine that doesn't have a secure network interface configured with the same certificate.
Alternatively, you may need to increase your CONNECTTIMEOUT value for the network interface and/or increase your CONNECTATTEMPTS value in your STAF.cfg file.
17 File Open Error This indicates that there was an error opening the requested file. Some possible explanations are that the file/path does not exist, contains invalid characters, or is locked.
Note: Additional information regarding which file could not be opened may be provided in the result passed back from the submit call.
18 File Read Error This indicates that there was an error while trying to read data from a file.
Note: Additional information regarding which file could not be read and why may be provided in the result passed back from the submit call.
19 File Write Error This indicates that there was an error while trying to write data to a file.
Note: Additional information regarding which file could not be written to may be provided in the result passed back from the submit call.
20 File Delete Error This indicates that there was an error while trying to delete a file or directory.
Note: Additional information regarding which file or directory could not be deleted may be provided in the result passed back from the submit call.
21 STAF Not Running This indicates that STAFProc is not running on the local machine with the same STAF_INSTANCE_NAME (and/or the same STAF_TEMP_DIR if on a Unix machine).
Notes:

If the STAF_INSTANCE_NAME environment variable is not set, it defaults to "STAF".
On Unix, if the STAF_TEMP_DIR environment variable is not set, it defaults to "/tmp". This environment variable is not used on Windows.
This error can also occur when submitting a request using the local IPC interface on a Unix machine if the socket file that the local interface uses has been inadvertently deleted.
On Windows, with User Account Controls (UAC) enabled, if STAFProc.exe is being run as an Administrator, this error will occur if a STAF service request is not also run as an Administrator (e.g. from an "Administrator: Command Prompt") or if programs that submit STAF service requests using STAF APIs for Java, C/C++, Perl, Python, or Tcl are not run an an Administrator. See section "5.1.2 Running STAFProc on Windows with User Account Controls (UAC) Enabled" in the STAF User's Guide for more information.
More information on this error may be displayed if you set special environment variable STAF_DEBUG_21=1 and resubmit your STAF service request.

22 Communication Error This indicates an error transmitting data across the network, or to the local STAF process. For example, you would receive this error if STAFProc.exe was terminated in the middle of a service request, or if a bridge went down in the middle of a remote service request. This can also indicate that the requested endpoint is not valid (e.g. it has an invalid network interface and port combination such as a non-secure tcp interface with the port for a secure ssl interface).
23 Trustee Does Not Exist You have requested to delete a trustee, and the trustee does not exist. Verify that you have specified the correct trustee.
24 Invalid Trust Level You have attempted to set a machine or default trust level to an invalid level. The valid trust levels are from zero to five.
25 Insufficient Trust Level You have submitted a request for which you do not have the required trust level to perform the request.
Note: Additional information regarding the required trust level may be provided in the result passed back from the submit call.
26 STAF Registration Error This indicates that an external service encountered a problem when trying to register with STAF. Ensure that STAF has been properly installed and configured.
27 Service Configuration Error This indicates an error with the configuration of an external service. One possible explanation is that the LIBRARY you specified when configuring the service does not exist. Or, if you specified the EXECUTE option, verify that the executable exists and has the execute permission. Or, if you specified the PARMS option, verify that all of the service configuration are valid. Consult the appropriate documentation for the service to verify whether you have configured the service properly, or contact the service provider.
Note: Additional information regarding why the service configuration failed may be provided in the result passed back from the submit call.
28 Queue Full This indicates that you are trying to queue a message to a handle's queue, but the queue is full. The maximum queue size can be increased by using the MAXQUEUESIZE statement in the STAF Configuration File.
29 No Queue Element This indicates that you tried to GET or PEEK a particular element in a queue, but no such element exists, or the queue is empty.
30 Notifiee Does Not Exist This indicates that you are trying to remove a message notification for a machine/process/priority combination which does not exist in the notification list.
31 Invalid API Level This indicates that a process has tried to call an invalid level of an internal STAF API. If this error occurs, report it to the authors.
32 Service Not Unregisterable This indicates that you are trying to unregister a service that is not unregisterable. Note that internal services are not unregisterable.
33 Service Not Available This indicates that the service you requested is not currently able to accept requests. The service may be in the process of initializing or terminating.
34 Semaphore Does Not Exist This indicates that you are trying to release, query, or delete a semaphore that does not exist.
35 Not Semaphore Owner This indicates that you are trying to release a semaphore for which your process is not the current owner.
36 Semaphore Has Pending Requests This indicates that you are trying to delete either a mutex semaphore that is currently owned or an event semaphore that has waiting processes.
37 Timeout This indicates that you submitted a request with a timeout value and the request did not complete within the requested time.
38 Java Error This indicates an error performing a Java native method call. A description of the error will be returned in the result passed back from the submit call.
39 Converter Error This indicates an error performing a codepage conversion. The most likely cause of this error is that STAF was not properly installed. However, it is possible that you are currently using a codepage that was not present or specified during STAF installation.
40 Move Error This indicates that there was an error while trying to move a file or directory.
Note: Additional information regarding the error may be provided in the result passed back from the submit call.
41 Invalid Object This indicates that an invalid object was specified to a STAF API. If you receive this return code via a standard STAFSubmit call, report it to the authors and the service provider.
42 Invalid Parm This indicates that an invalid parameter was specified to a STAF API. If you receive this return code via a standard STAFSubmit call, report it to the authors and the service provider.
43 Request Number Not Found This indicates that the specified Request Number was not found. The specified Request Number may be invalid, or the request's information may no longer be available from the Service Service (for example, if the SERVICE FREE command had previously been issued for the request number).
44 Invalid Asynch Option This indicates that an invalid Asynchronous submit option was specified.
45 Request Not Complete This indicates that the specified request is not complete. This error code would be returned, for example, if you requested the result of a request which has not yet completed.
46 Process Authentication Denied This indicates that the userid/password you specified could not be authenticated. The userid/password may not be valid or authentication may be disabled.
47 Invalid Value This indicates that an invalid value was specified. This is closely related to the Invalid Request String return code, but indicates that a specific value in the request is invalid. For example, you may not have specified a number where a number was expected.
Note: Additional information regarding which value is invalid may be provided in the result passed back from the submit call.
48 Does Not Exist This indicates that the item you specified does not exist.
Note: Additional information regarding which item could not be found may be provided in the result passed back from the submit call.
49 Already Exists This indicates that the item you specified already exists.
Note: Additional information regarding which item already exists may be provided in the result passed back from the submit call.
50 Directory Not Empty This indicates that you have tried to delete a directory, but that directory is not empty.
Note: Additional information specifying the directory which could not be deleted may be provided in the result passed back from the submit call.
51 Directory Copy Error This indicates that you have tried to copy a directory, but errors occurred during the copy.
Note: Additional information specifying the entries which could not be copied may be provided in the result passed back from the submit call. More details about why a specific file could not be copied may be provided by submitting a COPY FILE request instead of a COPY DIRECTORY request.
52 Diagnostics Not Enabled This indicates that you tried to record diagnostics data, but diagnostics have not been enabled. You must enable diagnostics before you can record diagnostics data.
53 Handle Authentication Failed This indicates that the user, credentials, and/or authenticator you specified could not be authenticated. The user/credentials may not be valid or the authenticator may not be registered.
Note: Additional information specifying why authentication was denied may be provided in the result passed back from the submit call.
54 Handle Already Authenticated This indicates that the handle is already authenticated. The handle must be unauthenticated in order to be authenticated.
55 Invalid STAF Version This indicates that the version of STAF (or the version of a STAF service) is lower than the minimum required version.
56 Request cancelled This indicates that the request has been cancelled.
Note: Additional information specifying why the request was cancelled may be provided in the result passed back from the submit call.
57 Create Thread Error This indicates that a problem occurred creating a new thread. One possible explanation is that there's not enough memory available to create a new thread.
Note: Additional information specifying why creating a new thread failed may be provided in the result passed back from the submit call.
58 Maximum Size Exceeded This indicates that the size of a file exceeded the maximum size allowed (e.g. per the MAXRETURNFILESIZE operational parameter or per the MAXRETURNFILESIZE setting for the STAX service). A maximum file size is usually set to prevent the creation of result strings that require more memory than is available which can cause errors or crashes.
Note: Additional information specifying why this error occurred may be provided in the result passed back from the submit call.
59 Maximum Handles Exceeded This indicates that a new handle could not be created/registered because the maximum number of active handles allowed by STAF has been exceeded. You need to delete one or more handles that are no longer being used. The Handle service's LIST HANDLES SUMMARY request provides information on the maximum number of active STAF handles and this may be helpful in better understanding why this error occurred.
60 Not Pending Requester You cannot cancel a pending request your handle did not submit unless you specify the FORCE option.
4000+ Service Defined Error codes of 4000 and beyond are service specific error codes. Either see the appropriate section in this document for the syntax of the service's requests, or contact the provider of the service.

Error Code	Meaning	Comment
0	No error
1	Invalid API	This indicates that a process has tried to call an invalid internal STAF API. If this error occurs, report it to the authors.
2	Unknown Service	You have tried to submit a request to a service that is unknown to STAFProc. Verify that you have correctly registered the service.
3	Invalid Handle	You are passing an invalid handle to a STAF API. Ensure that you are using the handle you received when you registered with STAF.
4	Handle already exists	This indicates that you are trying to register a process with one name when that process has already been registered with a different name. If you register the same process multiple times, ensure that you use the same name on each registration call. Note: If you receive this error code when trying to perform an operation other than registering a service, report it to the authors.
5	Handle does not exist	You are trying to perform an operation on a handle that does not exist. For example, you may be trying to stop a process, but you are specifying the wrong handle.
6	Unknown Error	An unknown error has occurred. This error is usually an indication of an internal STAF error. If this error occurs, report it the authors.
7	Invalid Request String	You have submitted an improperly formatted request to a service. See the appropriate section in this document for the syntax of the service's requests, or contact the provider of the service. Note: Additional information regarding the exact syntax error may be provided in the result passed back from the submit call.
8	Invalid Service Result	This indicates an internal error with the service to which a request was submitted. If this error occurs, report it to the authors and the service provider.
9	Rexx Error	This indicates an internal error in an external Rexx service. If this error occurs, report it to the authors and the service provider. Note: The actual Rexx error code will be returned in the result passed back from the submit call.
10	Base OS Error	This indicates that a base operating system error was encountered. Note: The actual base operating system error code, and possibly additional information about the error, will be returned in the result passed back from the submit call.
11	Process Already Complete	You are trying to perform an invalid operation on a process that has already completed. For example, you may be trying to stop the process or register for a process end notification.
12	Process Not Complete	You are trying to free process information for a process that is still executing.
13	Variable Does Not Exist	You are trying to get, remove, or resolve a variable that does not exist. Remember that variables are case sensitive. The name of the variable that does not exist will be in the result passed back from the submit call.
14	UnResolvable String	You have requested to resolve a string that cannot be resolved. This indicates that you have exceeded the resolution depth of the VAR service. The most common cause of this is recursive variables definitions.
15	Invalid Resolve String	The string you requested to be resolved has a non-matching left or right curly brace. Ensure that all variable references have both left and right curly braces.
16	No Path To Endpoint	This indicates that STAFProc was not able to submit the request to the requested endpoint (i.e. target machine). This error usually indicates one or more of the following: STAFProc is not running on the target machine. The requested endpoint is not valid. The network interface or port for the requested endpoint is not supported. A firewall is blocking communication via the port for the requested endpoint. A secure network interface is being used to communicate to a machine that doesn't have a secure network interface configured with the same certificate. Alternatively, you may need to increase your CONNECTTIMEOUT value for the network interface and/or increase your CONNECTATTEMPTS value in your STAF.cfg file.
17	File Open Error	This indicates that there was an error opening the requested file. Some possible explanations are that the file/path does not exist, contains invalid characters, or is locked. Note: Additional information regarding which file could not be opened may be provided in the result passed back from the submit call.
18	File Read Error	This indicates that there was an error while trying to read data from a file. Note: Additional information regarding which file could not be read and why may be provided in the result passed back from the submit call.
19	File Write Error	This indicates that there was an error while trying to write data to a file. Note: Additional information regarding which file could not be written to may be provided in the result passed back from the submit call.
20	File Delete Error	This indicates that there was an error while trying to delete a file or directory. Note: Additional information regarding which file or directory could not be deleted may be provided in the result passed back from the submit call.
21	STAF Not Running	This indicates that STAFProc is not running on the local machine with the same STAF_INSTANCE_NAME (and/or the same STAF_TEMP_DIR if on a Unix machine). Notes: If the STAF_INSTANCE_NAME environment variable is not set, it defaults to "STAF". On Unix, if the STAF_TEMP_DIR environment variable is not set, it defaults to "/tmp". This environment variable is not used on Windows. This error can also occur when submitting a request using the local IPC interface on a Unix machine if the socket file that the local interface uses has been inadvertently deleted. On Windows, with User Account Controls (UAC) enabled, if STAFProc.exe is being run as an Administrator, this error will occur if a STAF service request is not also run as an Administrator (e.g. from an "Administrator: Command Prompt") or if programs that submit STAF service requests using STAF APIs for Java, C/C++, Perl, Python, or Tcl are not run an an Administrator. See section "5.1.2 Running STAFProc on Windows with User Account Controls (UAC) Enabled" in the STAF User's Guide for more information. More information on this error may be displayed if you set special environment variable STAF_DEBUG_21=1 and resubmit your STAF service request.
22	Communication Error	This indicates an error transmitting data across the network, or to the local STAF process. For example, you would receive this error if STAFProc.exe was terminated in the middle of a service request, or if a bridge went down in the middle of a remote service request. This can also indicate that the requested endpoint is not valid (e.g. it has an invalid network interface and port combination such as a non-secure tcp interface with the port for a secure ssl interface).
23	Trustee Does Not Exist	You have requested to delete a trustee, and the trustee does not exist. Verify that you have specified the correct trustee.
24	Invalid Trust Level	You have attempted to set a machine or default trust level to an invalid level. The valid trust levels are from zero to five.
25	Insufficient Trust Level	You have submitted a request for which you do not have the required trust level to perform the request. Note: Additional information regarding the required trust level may be provided in the result passed back from the submit call.
26	STAF Registration Error	This indicates that an external service encountered a problem when trying to register with STAF. Ensure that STAF has been properly installed and configured.
27	Service Configuration Error	This indicates an error with the configuration of an external service. One possible explanation is that the LIBRARY you specified when configuring the service does not exist. Or, if you specified the EXECUTE option, verify that the executable exists and has the execute permission. Or, if you specified the PARMS option, verify that all of the service configuration are valid. Consult the appropriate documentation for the service to verify whether you have configured the service properly, or contact the service provider. Note: Additional information regarding why the service configuration failed may be provided in the result passed back from the submit call.
28	Queue Full	This indicates that you are trying to queue a message to a handle's queue, but the queue is full. The maximum queue size can be increased by using the MAXQUEUESIZE statement in the STAF Configuration File.
29	No Queue Element	This indicates that you tried to GET or PEEK a particular element in a queue, but no such element exists, or the queue is empty.
30	Notifiee Does Not Exist	This indicates that you are trying to remove a message notification for a machine/process/priority combination which does not exist in the notification list.
31	Invalid API Level	This indicates that a process has tried to call an invalid level of an internal STAF API. If this error occurs, report it to the authors.
32	Service Not Unregisterable	This indicates that you are trying to unregister a service that is not unregisterable. Note that internal services are not unregisterable.
33	Service Not Available	This indicates that the service you requested is not currently able to accept requests. The service may be in the process of initializing or terminating.
34	Semaphore Does Not Exist	This indicates that you are trying to release, query, or delete a semaphore that does not exist.
35	Not Semaphore Owner	This indicates that you are trying to release a semaphore for which your process is not the current owner.
36	Semaphore Has Pending Requests	This indicates that you are trying to delete either a mutex semaphore that is currently owned or an event semaphore that has waiting processes.
37	Timeout	This indicates that you submitted a request with a timeout value and the request did not complete within the requested time.
38	Java Error	This indicates an error performing a Java native method call. A description of the error will be returned in the result passed back from the submit call.
39	Converter Error	This indicates an error performing a codepage conversion. The most likely cause of this error is that STAF was not properly installed. However, it is possible that you are currently using a codepage that was not present or specified during STAF installation.
40	Move Error	This indicates that there was an error while trying to move a file or directory. Note: Additional information regarding the error may be provided in the result passed back from the submit call.
41	Invalid Object	This indicates that an invalid object was specified to a STAF API. If you receive this return code via a standard STAFSubmit call, report it to the authors and the service provider.
42	Invalid Parm	This indicates that an invalid parameter was specified to a STAF API. If you receive this return code via a standard STAFSubmit call, report it to the authors and the service provider.
43	Request Number Not Found	This indicates that the specified Request Number was not found. The specified Request Number may be invalid, or the request's information may no longer be available from the Service Service (for example, if the SERVICE FREE command had previously been issued for the request number).
44	Invalid Asynch Option	This indicates that an invalid Asynchronous submit option was specified.
45	Request Not Complete	This indicates that the specified request is not complete. This error code would be returned, for example, if you requested the result of a request which has not yet completed.
46	Process Authentication Denied	This indicates that the userid/password you specified could not be authenticated. The userid/password may not be valid or authentication may be disabled.
47	Invalid Value	This indicates that an invalid value was specified. This is closely related to the Invalid Request String return code, but indicates that a specific value in the request is invalid. For example, you may not have specified a number where a number was expected. Note: Additional information regarding which value is invalid may be provided in the result passed back from the submit call.
48	Does Not Exist	This indicates that the item you specified does not exist. Note: Additional information regarding which item could not be found may be provided in the result passed back from the submit call.
49	Already Exists	This indicates that the item you specified already exists. Note: Additional information regarding which item already exists may be provided in the result passed back from the submit call.
50	Directory Not Empty	This indicates that you have tried to delete a directory, but that directory is not empty. Note: Additional information specifying the directory which could not be deleted may be provided in the result passed back from the submit call.
51	Directory Copy Error	This indicates that you have tried to copy a directory, but errors occurred during the copy. Note: Additional information specifying the entries which could not be copied may be provided in the result passed back from the submit call. More details about why a specific file could not be copied may be provided by submitting a COPY FILE request instead of a COPY DIRECTORY request.
52	Diagnostics Not Enabled	This indicates that you tried to record diagnostics data, but diagnostics have not been enabled. You must enable diagnostics before you can record diagnostics data.
53	Handle Authentication Failed	This indicates that the user, credentials, and/or authenticator you specified could not be authenticated. The user/credentials may not be valid or the authenticator may not be registered. Note: Additional information specifying why authentication was denied may be provided in the result passed back from the submit call.
54	Handle Already Authenticated	This indicates that the handle is already authenticated. The handle must be unauthenticated in order to be authenticated.
55	Invalid STAF Version	This indicates that the version of STAF (or the version of a STAF service) is lower than the minimum required version.
56	Request cancelled	This indicates that the request has been cancelled. Note: Additional information specifying why the request was cancelled may be provided in the result passed back from the submit call.
57	Create Thread Error	This indicates that a problem occurred creating a new thread. One possible explanation is that there's not enough memory available to create a new thread. Note: Additional information specifying why creating a new thread failed may be provided in the result passed back from the submit call.
58	Maximum Size Exceeded	This indicates that the size of a file exceeded the maximum size allowed (e.g. per the MAXRETURNFILESIZE operational parameter or per the MAXRETURNFILESIZE setting for the STAX service). A maximum file size is usually set to prevent the creation of result strings that require more memory than is available which can cause errors or crashes. Note: Additional information specifying why this error occurred may be provided in the result passed back from the submit call.
59	Maximum Handles Exceeded	This indicates that a new handle could not be created/registered because the maximum number of active handles allowed by STAF has been exceeded. You need to delete one or more handles that are no longer being used. The Handle service's LIST HANDLES SUMMARY request provides information on the maximum number of active STAF handles and this may be helpful in better understanding why this error occurred.
60	Not Pending Requester	You cannot cancel a pending request your handle did not submit unless you specify the FORCE option.
4000+	Service Defined	Error codes of 4000 and beyond are service specific error codes. Either see the appropriate section in this document for the syntax of the service's requests, or contact the provider of the service.