| Common Problems (and Their Solutions)

## Runtime Problems

> Here are the most common problems that you might encounter when you try to run a successfully compiled program that uses the JNDI classes.

> #### Class Not Found

> Problem: You get a `NoClassDefFoundError` when running your program.

> Cause: You did not include the JNDI classes (`jndi.jar`) in your classpath, or you did not install the JNDI classes properly.

> Solution: The Java 2 SDK, v1.3 already include the JNDI classes so if you are using this version you should not get this error.

> If you are not using the Java 2 SDK, v1.3, then the way you that include the JNDI classes your execution environment depends on the environment. If you are using the Java 2 SDK, v1.2, then make sure that `jndi.jar` is in the JAVA_HOME`/jre/lib/ext` directory, where JAVA_HOME is the directory that contains the Java Runtime Environment (JRE). Note that on some platforms, separate `jre/lib/ext` directories exist for the JRE and the SDK. Make sure that the JNDI JARs have been installed in both `jre/lib/ext` directories. If you are using the `java` interpreter from the JDK 1.1, then add the JARs either to your `CLASSPATH` environment variable or 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 a `NoInitialContextException`.

> Cause: You did not specify which implementation to use for the initial context. Specifically, the `Context.INITIAL_CONTEXT_FACTORY` environment property was not set to the class name of the factory that will create the initial context. Or, you did not make available to the program the classes of the service provider named by `Context.INITIAL_CONTEXT_FACTORY`.

> Solution: Set the `Context.INITIAL_CONTEXT_FACTORY` environment property to the class name of the initial context implementation that you are using. See The Basics trail for details.

> If the property was set, then make sure that the class name was not mistyped, and that the class named is available to your program (either in its classpath or installed in the `jre/lib/ext` directory of the JRE). The Java 2 SDK, v1.3 includes service providers for LDAP, COS naming, and the RMI registry. All other service providers must be installed and added to the execution environment.

> #### Connection Refused

> Problem: You get a `CommunicationException`, indicating "connection refused."

> Cause: 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. Or, maybe you 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. The way that you perform this check depends on the LDAP server that you are using. Usually, an administrative console or tool is available that you can use to administer the server. You may use that tool to verify the server's status.

> #### Connection Fails

> Problem: The LDAP server responds 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 LDAP v3 connection requests. Some servers (especially public servers) do not respond correctly to the LDAP v3, ignoring the requests instead of rejecting them. Also, some LDAP v3 servers have problems handling a control that Sun's LDAP service provider automatically sends and often return a server-specific failure code.

> 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; if that fails, then it uses the LDAP v2. If the server silently ignores the v3 request, then the provider will assume that the request worked. To work around such servers, you must explicitly set the protocol version to ensure proper behavior by the server.

> If the server is a v3 server, then try setting the following environment property before creating the initial context:

> >     env.put(Context.REFERRAL, "throw");

> This will turn off the control that the LDAP provider sends automatically. (See the Referrals lesson for details.)

> #### Program Hangs

> Problem: The program 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 that they expend on a per-request basis.

> Or, you tried to use Secure Socket Layer (SSL) against a server/port that does not support it, and vice versa (that is, you tried to use 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, then retry your request using a query that will return a single result or only a few results. This will help you to determine whether the server is alive. If it is, then you can broaden your initial query and resubmit it.

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

> #### Name Not Found

> Problem: You get a `NameNotFoundException`.

> Causes: When you initialized 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 supplied a name such as `"cn=Joe,c=us"`, then the full name that you passed to the LDAP service was `"cn=Joe,c=us,o=JNDITutorial"`. If this was really the name that you intended, then you should check your server to make sure that it contains such an entry.

> Also, the Netscape Directory Server returns this error if you supply an incorrect distinguished name for authentication purposes. For example, the LDAP provider will throw a `NameNotFoundException` if you set the `Context.SECURITY_PRINCIPAL` environment property to `"cn=Admin, o=Tutorial"`, and `"cn=Admin, o=Tutorial"` is not an entry on the LDAP server. The correct error for the Netscape Directory Server to return actually should be something related to authentication, rather than "name not found."

> Solution: Verify the name that you supplied is that of an entry existing on the server. You can do this by listing the entry's parent context or using some other tool such as the directory server's administration console.

| Common Problems (and Their Solutions)