Previous | Next | Trail Map | Getting Started | Common Problems (and Their Solutions)

Runtime Problems

Class Not Found

Problem: You get NoClassDefFoundError when running your program.

Cause: You have not included the classes for the JNDI (jndi.jar) or the service providers (for example, ldap.jar and providerutil.jar) that you are using in your classpath.

Solution: The way you include the JNDI and service provider classes to your classpath depends on your execution environment. Using the java interpreter, you can either add the JARs to your CLASSPATH environment variable or add them to the -classpath option in your java command line.

For an applet, you need to make the JNDI and provider classes available to that applet (for example, by adding them to the archive option).

No Initial Context

Problem: You get NoInitialContextException.

Cause: You have not specified which implementation to use for the initial context. Specifically, the Context.PROVIDER_URL(in the API reference documentation) environment property has not been set to the class name of the factory that will create the initial context.

Solution: Set the Context.PROVIDER_URL environment property to the class name of the initial context implementation you are using. See trail for details.

Connection Refused

Problem: You get a CommunicationException indicating "connection refused".

Cause: This happens when the server and port identified by the Context.PROVIDER_URL environment property is not being served by the server. Perhaps someone has disabled or turned off the machine on which the server is running. Perhaps you have mistyped the server's name or port number.

Solution: Check that there is indeed a server running on that port and restart the server if necessary.

Connection Fails

Problem: The LDAP server is responding to other utilities (such as its administration console) but does not seem to respond to your program's requests.

Cause: The server does not respond to the LDAP v3 connection requests. Some servers (especially public servers) do not respond correctly to the LDAP v3 and just ignores the requests instead of rejecting them.

Solution. Try setting the environment property "java.naming.ldap.version" to "2". The LDAP service provider by default attempts to connect to an LDAP server using the LDAP v3 and fails over to the LDAP v2. If the server silently ignores the v3 request, the provider will assume that the v3 request worked. To work around such servers, you must explicitly set the protocol version to ensure proper behavior on the part of the server.

Program Hangs

Problem: The program just hangs.

Causes: Some servers (especially public ones) won't respond (not even with a negative answer) if you attempt to perform a search that would generate too many results or that would require the server to examine too many entries in order to generate the answer. Such servers are trying to limit the amount of resources they expend on a per-request basis.

Another cause is if you try to use SSL against a server/port that does not support it, and vice versa (that is, by using a plain socket to talk to an SSL port).

Solution: If your program is hanging because the server is trying to restrict the use of its resources, you should retry your request using a query that will return a single result or only a few results. This will help you determine whether the server is alive. You can then narrow your initial query and resubmit it.

If your program is hanging because of SSL problems, you need to find out whether the port is an SSL port and then set the Context.SECURITY_PROTOCOL(in the API reference documentation) environment property appropriately. If the port is an SSL port, this property should be set to "ssl". If it is not an SSL port, this property should not be set.

Name Not Found

Problem: You get NameNotFoundException.

Causes: When you initialize the initial context for the LDAP, you supply a root distinguished name. For example, if you set the Context.PROVIDER_URL environment property for the initial context to "ldap://ldapserver:389/o=JNDITutorial", and subsequently supply a name like "cn=Joe,c=us", the full name that you are passing to the LDAP service is "cn=Joe,c=us,o=JNDITutorial". If this is really the name you intended, then you should check your server to make sure that it contains such an entry.

The Netscape Directory Server also returns this error if you supply an incorrect distinguished name for authentication purposes. For example, if you set Context.SECURITY_PRINCIPAL(in the API reference documentation) environment property to "cn=Admin, o=Tutorial", and Context.PROVIDER_URL was set to "ldap://ldapserver/o=Tutorial", and if "cn=Admin, o=Tutorial" is not an entry on the server "ldapserver", the LDAP provider will throw NameNotFoundException(in the API reference documentation). The correct error for the Netscape Directory Server to return should actually be something related to authentication, rather than name-not-found.

Solution: You should verify that the name you supplied is that of an entry that exists on the server. You can do so by listing the entry's parent context or using some other tools such as the directory server's administration console.


Previous | Next | Trail Map | Getting Started | Common Problems (and Their Solutions)