Chapter 5 eDirectory/NDS Error Codes Explained
DS errors occur during the processing of a directory services (DS) request or the execution of a DS background process. These errors can happen as a result of a hardware or software failure, data inconsistency, or unexpected responses received; therefore, when you’re troubleshooting a problem, it is essential that you know where the error originated, the condition that caused the error, and what the error code or message means. Unfortunately, computer-generated error messages are notoriously cryptic at best and frequently don’t easily provide the source of the error. For example, a DS error can be generated from one of three possible sources:
The DS service running on the server
The client application (workstation based or server based)
The DS agent (DSA) running on the server.
It gets even more frustrating if multiple causes can result in the same error code.
NOTE
Each DS -capable server runs both DS service (which processes DS requests locally) and the DSA service. The DSA tree-walks and queries other DS servers on behalf of the requesting client—which can be either a workstation or another server—if the local server doesn’t have the requested information.
By examining the code number returned or associated with an error message, you can determine the most likely source (the server, the client, or the DSA) and the possible cause of the DS error. Keep in mind that the information provided here does not necessarily give remedies; this chapter provides developers’ explanations of the errors. Several factors can help you to identify the root cause of an error and then eliminate or correct the error, including the following:
An understanding of DS processes (see Chapter 6, “Understanding Common eDirectory Processes”)
An understanding of DS error code definitions and possible conditions under which they can occur (see Appendix A, “eDirectory Error Codes”)
Familiarity with the DS tree that is experiencing the error
Familiarity with the placement of the replicas
Familiarity with various DS diagnostic and repair tools, such as DSTrace, DSBrowse, DSRepair, and the eDirectory Maintenance Tool Box (eMBox) included with eDirectory 8.7 and higher (see Chapter 7, “Diagnostic and Repair Tools”).
This chapter provides information to help you understand the most commonly encountered DS error codes. You can use this as a starting point to further determine the actual cause of a problem and then formulate a corrective action plan. An exhaustive list and explanation of all the published DS error codes is presented in Appendix A.
The first step in dealing with DS problems is to understand the nature of the error. DS errors can be categorized into transitory DS errors and recurring DS errors. These terms refer to the conditions that cause the DS error to occur and not to the DS error code reported in response to the conditions. In addition to understanding the nature of a DS error, you need to have an understanding of the types of conditions that can cause DS errors to occur in order to narrow down the area in which to concentrate your troubleshooting efforts.
NOTE
Not all DS errors are bad errors. Some errors are considered normal errors. A normal error—perhaps a better term is informational error—is one that logically happens in the DS. Examples are the collision errors and DSA common request errors you see in DSTrace. These informational errors are displayed to help you see how DS handles processes such as user logins and changes in the DS. For example, DSTrace shows a -601 error (no such object) when a user tries to log in using a wrong context; this is an error from a programmatic point of view, but it’s not an error from the DS operation’s point of view.
As mentioned previously, transitory DS errors are errors that occur on an intermittent basis or that occur only for a short time and do not reoccur. These errors are generally caused by conditions external to the server that report the error; however, transitory errors can also occur due to data inconsistency between different replicas of the same partition.
A commonly encountered transitory DS error is error code -625 (transport failure). It is caused by communication failure between two servers that hold replicas of the same partition. The communication fault may be due to a down WAN connection or a disruption of the LAN (such as beaconing in a Token Ring environment). Both of these error conditions are external to the servers, out of the control of DS, and can’t be resolved by DS; however, when the communication link is reestablished, the DS -625 error automatically stops and does not reoccur unless the link is down again.
In a well-maintained, healthy DS tree, most of the DS errors are of the transitory type. Therefore, when you’re presented with a DS error, it is best to remember not to panic and to give DS some time (say, 30 minutes to an hour; 2 to 4 hours for a large tree or a situation that involves slow WANs) to see whether the error can be autocorrected.
As mentioned previously, a recurring DS error is an error that results from a permanent error condition that can’t be correctly resolved without human intervention. Errors of this type persist until the cause of the error is identified and corrected. It is important to note that not all recurring errors are attributed to DS or the DS databases.
Although most of the time error -625 is a transitory error, it can also be a recurring error. For example, if a server holding a replica of a partition is removed from the network without going through the proper procedure, the replica ring becomes inconsistent. This is a result of the fact that the other servers in the replica ring are not aware that this one server is no longer available and will continue to attempt to synchronize updates with this server. The resulting -625 error continues to be reported until the replica ring is repaired.
NOTE
For the procedure on repairing replica ring inconsistency, see Chapter 11, “Examples from the Real World.”
Another common recurring DS error is -601 (no such object). A DS user or an application attempting to access a nonexistent DS object causes this. For instance, say a user is trying to log in, but the context of the User object is wrong. The user will continue to receive this -601 error code after each attempt. Keep in mind, however, that this -601 error code may also be transitory, depending on the cause of the error. For example, the login process will check to see whether the Login Script attribute exists for a user before executing it. If the user does not have a personal login script, a - 138601 error will be returned to the login process.
DS errors can be divided into three categories: informational messages, communication-related errors, and errors due to data inconsistency. Informational messages are nonfatal errors that are returned by DS to the requesting client to inform it of one or more of the following conditions:
The request cannot be processed at this time due to outstanding operation. For example, you’re trying to perform a partitioning operation while a previous one is still in progress.
The request cannot be processed due to insufficient DS rights. For example, if the requesting client doesn’t have the Browse object right to an object, a -601 error (no such object) will be returned, even though the object does exist.
The information provided in the request is invalid or is missing some mandatory fields.
The request references a nonexistent object or object class.
An unexpected response was received while the request was being processed. For example, the source server cannot connect to another server for tree-walking purposes (error -635).
Communication-related errors are errors that result from LAN or WAN failures. Given that DS is a distributed and replicated database, DS must be able to communicate with other servers within the same DS tree. Any failure in the underlying hardware and software to provide the capability to communicate between servers results in disruption of DS processes and operations. Fortunately, communication-related DS errors are generally transitory and are resolved when the communication capability between servers is restored. Some possible causes of communication-related DS errors are as follows:
Faulty LAN drivers
Faulty LAN/WAN hardware, such as cable and network cards
Unreliable network infrastructure, such as slow or often congested WAN links
Incorrect server (internal) network addresses contained in the DS database of a server (perhaps the server didn’t receive the updated information from other servers in the replica ring due to other errors)
Duplicate server internal network addresses or IP addresses
Route and/or Service Advertising Protocol (SAP) filtering, or Service Location Protocol (SLP)–related problems.
NOTE
In NetWare 3 and NetWare 4, IPX INTERNAL NET is used in the AUTOEXEC.NCF to specify the server’s internal (Internetwork Packet Exchange [IPX]) address. In NetWare 5 and higher, ServerID is used instead. However, the server console command CONFIG still reports the value as the IPX internal network number.
Communication errors can result in DS data inconsistency, such as a user object existing in one replica but not in another. This is due to replicas of the same partition being out of sync; however, such inconsistencies are often transitory in nature and self-correct when communication is reestablished.
On the other hand, DS data inconsistency can be of the recurring type. For example, if the schema or one of the DS database files on a server is corrupted, DS can’t rectify the resulting data inconsistency automatically, and manual intervention is required.
To correctly identify the condition under which a specific DS error occurs, you need to know the meaning of the reported error code and the source of the error code. The rest of this chapter is dedicated to describing some of the most commonly encountered DS error codes and the possible conditions under which they occur. The discussions are divided into the following categories, based on the error code grouping:
Operating system–related DS error codes (-1 through -255)
DS client application programming interface (API) error codes (-301 through -399)
Server-based DS client library error codes (-400 through -599)
DSA error codes (-601 through -799, and -6001 through -6999).
NOTE
Error codes used by Novell’s DirXML (between -286 and -300) and SecureLogin (between -102 and -430) products overlap with the DS error codes. Therefore, you should be careful when interpreting the meaning of an error code if you have these products installed.
TIP
Due to the way the search engine works, when searching for DS error codes using Novell’s online support knowledge base, you enter the code using the positive version of a negative number that is reported. For instance, if you are looking for information about error code -6018, enter 6018 in the search box instead of –6018. Alternatively, you can put the negative number within quotes, such as "-6018". Otherwise, the search could result in a large number of irrelevant hits.
One set of server-based error codes, -4991 through -4999, is related to eDirectory errors, but these errors are not observed on the NetWare platform. These error codes are associated with the DHost process.
Because NDS was initially developed for the NetWare platform, NetWare Core Protocol (NCP) is used for communications between NetWare servers and between clients and the servers. In order for eDirectory running on Windows and Linux/Unix/Linux to properly communicate with the NetWare implementation, a special application, called DHost, is used. DHost sits underneath eDirectory and provides functionality on non-NetWare platforms that the NetWare operating system provides naturally. The services provided by DHost include the (small) NCP Engine to handle communications with NetWare servers, the Watchdog function to ensure that workstations running Client32 are still connected, and an event system to provide a way for applications to monitor the DS activity of the server.
NOTE
DHost error codes range between -4991 (0xFFFFEC81) and -4999 (0xFFFFEC79), and NCP Engine–related errors range between -5187 (0xFFFFEBBD) and -5199 (0xFFFFEBB1).
See Chapter 6 for a detailed discussion about the DS processes that generate the errors.
Error codes -1 through -255 are operating system–related errors (such as from the file system, IPX, the bindery NCP, and other operating system services) returned through DS. The operating system error codes are 1 byte in size and are mapped to -1 to -255 when returned as DS errors. For example, when an application makes a DS API call but didn’t allocate a large enough buffer for the data to be returned by the server, it results in a -119 error (buffer too small).
You normally do not come across these operating system–related DS error codes because the applications should trap them and take appropriate action; however, if the application fails to trap the error, you may encounter these error codes.
NOTE
In general, the error codes listed in this section are of more interest to programmers writing DS-aware applications than they are to network administrators.
Table 5.1 lists the operating system–related errors that you are most likely to see and what they mean. You can find a complete list of all the operating system–related errors in Appendix A.
You should pay special attention if you encounter error -149. It is an internal auditing error that should generally not happen in the first place unless there’s internal system corruption. If you encounter it, you need to contact Novell to resolve this error. Error -150 is important because it suggests that the server doesn’t have sufficient dynamic memory to process the current auditing request; this error could be due to RAM shortage or memory fragmentation on the server. If you encounter a -239 error, it means the server received a request made with an object or a property name containing illegal characters, such as a control character, a comma, a colon, a semicolon, a slash, a backslash, a question mark, an asterisk, or a tilde. This error may also be due to the fact that the DS module can’t map the supplied object or attribute name to its Unicode representation and could be a result of missing or corrupted Unicode files in the SYS:LOGINNLS directory on a NetWare server (winntsystem32
ls on Windows or /usr/share/nwlocale on Unix/Linux).
Some of these operating system–related error codes (such as -254 and -255) have multiple meanings. And because -001 to -255 are mostly server operating system error codes reported as DS errors, you need to be aware of the context under which the error code is returned in order to correctly interpret the cause of the error.
NOTE
Some of the error codes in the range of –001 through –255 may be caused by Secure Authentication Services (SAS), the Authentication Tool Box (ATB) library (on a NetWare server), or even the Novell SecureLogin product. Therefore, knowing the condition under which the error occurred will help you to correctly interpret the error code, thus helping you find the proper fix to the problem.
Error codes -301 through -399 are errors returned by DS client API library functions. For example, when an application makes a call to an API function using an invalid object name (such as CN=Test.O=ABC.O=TopLevel) a -314 error (invalid object name) will be returned because one Organization object is inside another Organization object, which is not allowed by the schema containment rules.
As with the DS operating system errors, you normally do not come across these client API DS error codes because the applications should have trapped them and taken appropriate action; however, if the application fails to trap the error, you might encounter these error codes. Sometimes, the error code is shown as part of the error message displayed by the application. For example, the NetWare Administrator application (nwadmn32.exe) displays error messages as shown in Figure 5.1.
In Figure 5.1, the ID number (945) is the index of the text message in the System Message Help file, and the number following the error code (35327) is a reference number that is strictly for Novell’s internal use.
NOTE
In general, the error codes listed in this section are of more interest to programmers writing DS-aware applications than they are to network administrators.
Table 5.2 lists some common DS client API library error codes. You can find a complete list of all the DS client API library errors in Appendix A.
Error -301 means the application is unable to allocate memory. This suggests that the client (workstation) may be low on memory or that the application has repeatedly allocated buffers and failed to release them (memory leak). Therefore, if you still receive this error code after closing all other applications running on the client, there’s a good chance the application has a memory leak and you need to contact the vendor for an update.
Error -348 means the application can’t locate the required Unicode file or files. This error can be due to one of two reasons. The first reason is that, because DS stores all characters using Unicode representation, DS-aware applications need access to country-code and code-page specific Unicode files. Often, a programmer may hard-code the country-code information into the software (typically country code 001 and code page 437, for the United States). When you try to run such an application on a workstation that’s configured for, say, German, it may fail with error -348 because the necessary Unicode files may not have been installed. In North America, these are a workstation’s default country settings:
Country code = 001 (United States)
Code page = 437 (United States)
These Unicode files are needed:
UNI_437.001
UNI_COL.001
UNI_MON.001
437_UNI.001
If you set the code page to 850 instead of 437 (the default), these required Unicode files are needed:
UNI_850.001
UNI_COL.001
UNI_MON.001
850_UNI.001
Sometimes even when the programmer retrieves the country information during runtime, you may still encounter the -348 error. It is important to realize that different operating system platforms use different code pages, even if the country code is the same. For example, the default DOS country setting in North America is country code 001 and code page 850; however, the default Windows NT/2000 North America country setting (for the Windows 32-bit GUI environment) is country code 001 and code page 1252. As a result, if you try to run a DOS-based DS-aware application in the command prompt box on Windows NT/2000, you might receive the -348 error because the Unicode files for code page 850 are not found.
The second reason that error code -348 might occur is that DS-aware applications search for Unicode files in the following locations, in the order listed:
1. The directory in which the DS-aware application is located
2. The NLS directory directly under the directory in which the DS-aware application resides (This is why you have NLS directories in LOGIN and PUBLIC on the NetWare server.)
3. Your search drives or paths
For example, if the application is installed on a NetWare server in SYS:NDSAPP, the application looks, in the following order, at SYS:NDSAPPS, SYS:NDSAPPSNLS, and your search drives. Therefore, you have to ensure that the Unicode files can be found in one of these locations.
Error codes -400 through -599 are errors returned by DS server-based client API library functions. They are typically generated by the DS module and other related modules, such as DSRepair. However, certain DS processes require the functionality from server modules such as the Unicode module. If one of these supporting modules encounters an error, the error may be passed back to DS, and the DS module will then report the error.
You generally do not encounter these error codes because they are mostly trapped and handled by the modules. But in case you do encounter these error codes, they are included here for your reference.
NOTE
In general, the error codes listed in this section are of more interest to programmers writing DS-aware applications than they are to network administrators.
Table 5.3 shows common DS client API library error codes specific to server-based applications. You can find a complete list of all the DS client API library error codes specific to server-based applications in Appendix A.
Many server-based API functions require the application to first be attached to and authenticated to the target server (thus receiving a valid server handle). If the application failed to first obtain a valid server handle before making the API call, error -400 is returned.
NOTE
The -400 error could also indicate that the target server is not available. Therefore, before you jump to the conclusion that there is a bug in the application, check that the target server is reachable.
The other most commonly encountered errors in this category are -405 and -406. These error codes result when one or more illegal characters are found in the server name and usernames, respectively. For example, depending on the API in question, the specified server name may just be the CN portion of the object name (such as TEST_SERVER1) rather than the full object name (such as TEST_SERVER1.Org_Unit.Org); the dots in the name would be considered illegal characters.
NOTE
As discussed in Chapter 2, “eDirectory Basics,” although a DS object name may be up to 255 characters in length, including context information, the CN portion of the object name is limited to 64 characters.
Error codes -601 through -799 and -6001 through -6999 are errors returned by the DSA that is running on the DS server. The DSA errors are what you generally see in the DSTrace screen and reported by various DS utilities, such as NetWare Administrator and ConsoleOne; therefore, you should be well versed in these error codes.
Table 5.4 shows some of the common error codes returned by the DSA. You can find a complete list of all the DSA error codes in Appendix A.
The -601 error is perhaps the most common DS error code that you will encounter. This error refers to the fact that the specified object is not found on the server replying to the request. The specified object context could be wrong, or the client might not have sufficient DS rights (such as Browse) to the object. If you see this error code in a DSTrace screen, it simply means the server handling the request doesn’t have the information and will have to perform a tree-walk; therefore, in most cases, a -601 error is an informational error.
Errors -602 and -603 mean the requested attribute value and attribute, respectively, are not found on the server replying to the request. The client may not have sufficient DS rights to the data. Unlike with the -601 error, however, with -602 and -603, no tree-walking will be performed to look for the information elsewhere.
Next to the -601 error, -625 is probably the second most commonly reported DSA error. Error -625 means the reporting server is unable to communicate with the target server. This is generally a result of the target server being down, a LAN/WAN outage, or some sort of routing problem.
The -698 error code is another nonfatal error. It means an attempt was made to start the NDS replica synchronization process with a target server, but the target server was busy synchronizing with another server. This is a transitory error, and the NDS replica synchronization process will reschedule. You are likely to see this error on partitions that have a large replica ring (say, 10 or more servers) or have slow or busy servers in the replica ring.
NOTE
To prevent data conflicts, a DS server will only receive inbound DS replica synchronization traffic from other servers, in the replica ring, one at a time. When two servers in the same replica ring try to synchronize to the same DS server before one of them completes the synchronization, the second server reports error –698 and retries at a later time.
A routing problem could result in a misleading -715 error code, which means the NDS checksum in the request packet is invalid. We have encountered one instance where a duplicate IPX network address on the network caused DS to erroneously report a -715 error. After removing the duplicate route, DS resolved the -715 error without further intervention, such as the need to run DSRepair.
If you don’t have sufficient privileges to modify an object’s attribute values, error -672 occurs. Similarly, when a server-based application authenticates to only the local server and not the DS tree, the application also results in a -672 error if the object it tries to modify does not exist in a replica held on that server. Incidentally, performing a send all operation by using eMBox may also result in a -672 error, although it works fine if you use the DSRepair module instead. In this situation, the error is due to the fact that eMBox does not have all the necessary information to perform the task. You must enter two data fields when you send all objects to every replica in the ring by using eMBox:
1. You must select the partition you want to perform the send all operation on. Make sure the radio button is not selected for the partition ID but is on the partition DN.
2. You must select the server object you want to send from (using the Server DN option). It must be a server that holds at least a read/write replica of the partition in question.
If you do not enter the correct information (as illustrated in Figure 5.2) into either of these two fields, you will most likely get a -672 error as a result.
WARNING
Remember that there is no way to do a send all to just one specific server in the replica ring. A send all will send all objects to all other servers in the replica ring. Therefore, with a large replica ring, it could take some time to complete, and a large volume of DS traffic could be generated.
Many of the -6001 through -6999 series of error codes were introduced for eDirectory 8.7 and higher. These error codes are mostly related to the operation of eDirectory Backup eMTool (called eMTool for short) and the roll-forward log (RFL) files. For instance, if RFL files from another server were used when restoring the eDirectory database via eMTool, error -6018 will be reported. If one or more of the required RFL files required for an eDirectory database restoration is missing, eMTool will report a -6024 error.
TIP
There is an interesting bug in the eMBox version 10410.68 (shipped with eDirectory 8.7.1) that occurs when you set the RFL directory name. If the name of the RFL directory is longer than eight characters, the eMBox client reports a –785 error, saying that it was unable to update the backup configuration information. This is misleading because -785 means an internal Directory Information Base error, but there isn’t one. The error is due to that the fact that although the eMBox client supports long directory names, the FLAIM engine is rejecting the long name (for some unknown reason). Therefore, the workaround is to use a directory name that is eight or fewer characters.
Also be aware that if the specified directory does not already exist, eMBox will return a -25 error, indicating an invalid directory.
This chapter presents a discussion of the various error types and some possible sources. The errors are broken into following categories: errors returned by the DS service running on the server, errors returned by the client application (workstation based or server based), and errors returned by the DSA running on the server.
Chapter 6 provides an in-depth look at the common DS processes and helps explain the causes of the errors.