Troubleshooting web service error messages

Using IBM Rational Application Developer 7.5.4 and IBM WebSphere Application Server 6.1 to find and fix problems

This article introduces tips for troubleshooting common web service errors that can creep in during application configuration. It explains the suggested methods for rectifying those issues using IBM Rational Application Developer Version 7.5.4. This is first of a series of articles about troubleshooting guidelines.


Monaswi Rai (, Technical Analyst, Leading Software MNC

author photoMonaswi Rai is a technical analyst in one of the leading software MNC. He has more than five years of experience in enterprise-level technologies and a master's degree in software engineering. He has received many awards and other recognition for his excellent project delivery and innovation. He has also submitted a PowerPoint template to Microsoft that has been downloaded more than 2000 times, worldwide, and been rated 4.0 out of 5 stars. His subject areas include Java 2 Platform, Enterprise Edition (J2EE), web services, service-oriented architecture (SOA), AJAX, spring, Hibernate, and CORBA.

29 June 2010

Also available in Chinese Portuguese


Are you ready to develop a web service platform by using IBM® Rational® Application Developer Version 7.5.4 and IBM® WebSphere® Application Server Version 6.1? Or are you noticing unusual error messages that don't tell you much about the root causes of the problems? Do you need to debug and find the root cause of those issues? This article will help you in finding a possible way out to address these problems.

You will learn basic techniques to diagnose various problems related to web services by using these IBM tools. This article emphasizes the application's environment-level issues and the issues that might come up during the web service configuration. However, it does not cover the technology- or framework-related issues in conjunction with web services, because those might vary according to the requirements of an application.

To get the most of this article, it is desirable that you should have some basic understanding of WebSphere application server and the Rational Application Developer setup; however emphasis has been given to describe the utmost details of the scenario, as far as possible, used in this article with possible illustrations of the issues.

Sample web services

You will build a sample web service, which can be useful for illustrating the common errors debugging through Rational Application Developer 7.5.4.

You will generate a sample web service name DisplayUnit which will be used to display the information on demand basis. The display unit web service uses three java files namely, and Code Listings 1, 2, and 3, which follow, contain the three Java files: Listing 1 is for, Listing 2 is for, and Listing 3 is

Listing 1.
package com.demo.display;
public class Customer {
	private String name;
	private Address ad;
	public Address getAddress() {
		ad = new Address();
		return ad;
	public String getName() {
		return name;
	public void setName(String name) { = name;
	public boolean setAddress(Address ad1) { = ad1;
		return true;
Listing 2.
package com.demo.display;

public class Address {
	private String city;
	private String zipCode;
	private String houseNo;
	public String getCity() {
		return city;
	public void setCity(String city) { = city;
	public String getHouseNo() {
		return houseNo;
	public void setHouseNo(String houseNo) {
		this.houseNo = houseNo;
	public String getZipCode() {
		return zipCode;
	public void setZipCode(String zipCode) {
		this.zipCode = zipCode;
Listing 3.
package com.demo.display;
import com.demo.display.Customer;
public class DisplayUnit {
	private String msg;
	private int id;
        private Address ad;
	public int getId() {
		return id;
	public void setId(int id) { = id;
	public String getMsg() {
		return msg;
	public void setMsg(String msg) {
		this.msg = msg;
	public Customer getCustomerDetails() {
		Customer cust = new Customer();
		return cust;
	public Address getAddress() {
		Customer cust = new Customer();
		return cust.getAddress();

Another sample web service that you would create is for Employee information. It is called as GenerateDetails, and it uses the files shown in Listings 4, 5, and 6.

Listing 4.
package com.service;

import com.employee.Address;
import com.employee.Employee;

public class GenerateDetails {
		public Employee showEmployeeDetails()
	Employee emp = new Employee();
	Address addr = new Address();
		return emp;
Listing 5.
package com.employee;

public class Employee  {
    private int id;
    private java.lang.String name;
    private com.employee.Address addr;

    public Employee() {
    public int getId() {
        return id;
    public void setId(int id) { = id;
    public java.lang.String getName() {
        return name;
    public void setName(java.lang.String name) { = name;
    public com.employee.Address getAddr() {
        return addr;
    public void setAddr(com.employee.Address addr) {
        this.addr = addr;
Listing 6.
package com.employee;

public class Address {
	public Address()
	private String zipCode;
	private String Location;
	private String Country;
	private String State;
	public String getCountry() {
		return Country;
	public void setCountry(String country) {
		Country = country;
	public String getLocation() {
		return Location;
	public void setLocation(String location) {
		Location = location;
	public String getState() {
		return State;
	public void setState(String state) {
		State = state;
	public String getZipCode() {
		return zipCode;
	public void setZipCode(String zipCode) {
		this.zipCode = zipCode;

This assumes that you are aware of how to create a sample web service through Rational Application Developer. However, there are situations where you might receive weird errors. The next section discusses those issues and continues to use this sample web service example.

"Connection refused" message

(DisplayUnit webservice)

This kind of error usually occurs because the server-side configuration is incorrect. The most common source is the configuration of the application server configuration where the applications have been deployed. If you are receiving a "Connection refused" error, try to test the WSDL (Web Service Description Language) with the web service test option, "Test with Web Service Explorer," that Rational Application Developer provides. Check the following investigation points for debugging the connection-refused error:

Check whether the WebSphere application server is registered in the Rational Application Developer server's profile or not. If it is not configured, follow the below guidelines to create a server profile for WebSphere in Rational Application Developer (for the current example)

  1. Select Window > Show View > Other option (see Figure 1), and then search for and select the Server view and then, under that, Servers.
Figure 1. Server view in Rational Application Developer 7.5.4
Drop-down menus path to the Servers view
  1. In the Servers view, click New Server (Figure 2), and configure the application server by providing the installed path of the application server. In this case:
    C:\Program Files\IBM\WebSphereV6.1\AppServer
Figure 2. Defining a new server instance in Rational Application Developer 7.5.4
WebSphere v6.1 server selected as new server

Define the application server

Follow the steps as shown, from Figure 3 to Figure 7, to define the application server in Rational Application Developer 7.5.4:

  1. In the New Server window (shown in Figure 3), click the Installed Runtimes button.
  2. In the Preferences window, click the Add button.
  3. Within that view, click Add and select WebSphere Application Server v6.1.
Figure 3. Choose the runtime application server version
Adding runtime server instance
  1. In the New Server Runtime window, select the installation directory of the WebSphere Application Server, and then click Finish.
Figure 4. Select an installation directory of WebSphere Application Server
New Server Runtime details added
  1. Verify whether the new application server is listed in Installed Runtimes or not.
Figure 5. Verify the installed server
Installed Runtime list in Preferences window
  1. Click Next in the New Server window (Figure 2) after defining the new server in the installed runtime environment. Verify the WebSphere configurations and click Finish.
Figure 6. WebSphere Application Server V6.1 configuration setting
WebSphere server settings window
  1. After you click the Finish button, as shown in Figure 6, you see the new configured application server in the Server view of Rational Application Developer (Figure 7).
Figure 7. Server status
WebSphere Servers tab
  1. From the Rational Application Developer server profile, verify whether the application is started or not? Click the listed application server in the Server view of Rational Application Developer. If the application is installed and started in the configured application server, you will see the started status in the Server view (see Figure 8, segment 3).
    Note: The application server listed in the Server view should be started by right-clicking the server's name and selecting the Start option. Otherwise, it will not list any application inside of that (see Figure 7).

From the first screen segment (1) in Figure 8, which shows WebSphere and web service status check, you can see that there is no application started in the application server (because there is no status shown under the status section). That can also be one of the reasons for the "Connection refused" message. If the registered application server is the only running WebSphere instance in your machine, try logging in to the administrative console of the application server and restarting the application from the server console. If the problem persists while restarting, it would be better to redeploy the web service, because the application server is not showing any stopped status. Instead, it is showing a blank status, so you cannot be sure that the application is stopped properly and that it doesn't contain any internal (application-specific) problems.

Figure 8. WebSphere and the deployed web service project status (3 images)
WebSphere and web service status check

As shown in the WebSphere and web service status check, image (view 2 in Figure 8), if you encounter just a server state and, under that, there is no application state, it is clear that there is no application deployed in the application server. Try to deploy the application by using Rational Application Developer: Right-click the main service class and then click Create web service.

For further information, see the IBM® Redbooks® Rational Application Developer Version 7 Programming Guide, the IBM WebSphere Version 6 Web Services Handbook for Development and Deployment, or any of IBM tutorial about creating web service creation by using Rational Application Developer. Links are located in the Resources section.

Even if you have deployed the application but are not sure why the respective folders are not created in the WebSphere application server's directory, the configuration shown in Figure 9 will help you in deploying the application at the server's location. Please select the option mentioned in the image: WebSphere Application Server Configuration

Figure 9. WebSphere Application Server configuration settings
WebSphere Server Configuration settings

If the highlighted option (outlined by the rectangular box) is not enabled, this is one of the primary reasons as why the web service which is bundled as an EAR (enterprise archive) file is not copied in the server's location.

To speed up the debugging and testing, if you have a test server installed in your Rational Application Developer IDE, then you can avoid most server configuration delays. You can choose this feature either during installation or by using Rational Installation manager if you wish to install this feature later. Having a test server installed will result in the automatic creation of the server with the associated default profile in a new workspace.

Unable to locate a valid EngineConfigurationFactory

(GenerateDetails web service)

Sometimes, you might receive the following error while invoking the web service class (the error description would be similar to one of the following errors):

E WSWS1002E: An error occurred while processing the
Web services deployment descriptor for module:
WebServiceProject.war with error:
EngineConfigurationFactoryFinder$1 run
WSWS3345E: Error: Unable to locate
a valid EngineConfigurationFactory.

Your basic investigation should also include the following points:

  • The errors that describe ClassNotFoundException:
    Checking what class files are present in the server's location. Check whether you have the all of the necessary classes in your class folders or not. For example, Figure 10 shows that, from the web service project in the Navigator's view, the Employee class is not present under the web service project location that gets created when you try to build a web service. This kind of error doesn't appear. However, if you encounter such an error, cross-verify its class location first.
Figure 10. Web service project in the Navigator view
Web service in the Navigator view
  • If you encounter the EngineConfigurationFactory error, which doesn't tell you much about exactly where the problem is:

    The first and foremost step is to manually validate the locations of all of your class files. If not all of the class files are present, then you need to reconfigure your application so that the application server picks up all of the necessary classes during creation of the web service. This generally happens when few of the runtime configuration-related XML files are not written properly during web service generation.) You can also cross-verify by opening those XML files; however, it gets changed with new contents whenever you redeploy the web service. If you redeploy the whole web service application, it is a good practice to ensure that all runtime-generated files (which are specific to application servers) are created.

    For example, in the sample web service, we are using JAX-RPC. If you try to add the new operations in the implementation class and try to redeploy it, sometimes, even though the WSDL files gets generated, it doesn't generate the proper serializations and deserialization files. The chances of getting this sort of exception increase if you keep modifying the individual files without revalidating or republishing the web service WSDL files. For example, in the case of JAX-RPC, try finding the webservices.xml file and the corresponding WSDD files. Try redeploying the web service. For example, in case of JAX-RPC web services, right-click Java EE and then click Prepare for Deployment to generate the Java serializers and deserializers.

Hi there, this is a Web service!

(GenerateDetails web service)

If you are seeing the default web service messages while using the web service URL to validate whether the web service is up and running, however, you are not able to call the methods, you need to investigate the issue. This is also one of the scenarios where, if you ping the web service URL, you get the message saying "Hi there, this is a Web service!" but it doesn't yield any results for the exposed web service methods. This type of message is generally means that the web service is running fine. However, you could encounter a situation where your web service is active but couldn't process the request. This kind of issue is commonly due to a difference in the configuration files and the web service classes.

You can see from the deployed web service status check (Figure 11 shows "Status: Started") and Web service status request check that the application is running and, moreover, if you are pinging the web service URL, that it is displaying the messages that says "Hi there, this is a Web service!"

Figure 11. Deployed Web service project status
Installed Web service project status check
Figure 12. Deployed Web service status in running mode
Web service status request check

You can investigate the issue by using a few of the exposed web service methods to check whether you can receive the response or not. In addition to this, try to verify, through the logs, what is getting posted in the application server logs directory when you are using the web service.

This error description of the Employee class can be found in the SystemOut.log:

WSWS3034E: Error: The OperationDesc for getName was not matched
to a method of com.details.employee.Employee.
Debug:name: services/Employee
implClass: class com.details.employee.Employee

As it is appeared in the log, that getName method signature is not matching to the WSDL or application server-generated mapping XML.

java.lang.Exception: WSWS3352E: Error: Couldn't find a matching Java operation for WSDD operation

(GenerateDetails web service)

This error generally occurs when the service definition is not found in the web service implementation class; however, its references are being maintained in the web service configuration files (for example, in the WSDL files or in the runtime-generated XML mapping file). This situation normally happens when you forgot to remove the reference from the respective files (chances of that increase if you are doing a manual update). Using Rational Application Developer to regenerate the web service can sort out most of this kind of problem, which generally arises due to the difference in the configuration and service classes.

SRVE0255E: A WebGroup/Virtual Host to handle localhost: 9080 has not been defined

(GenerateDetails web service)

As shown in Figure 13, this kind of error generally arises when the web service is not properly deployed in the application server, or it has stopped working on the host or is not running in the application server. Restarting the web service should resolve this. However, if you are facing this issue even after that, then validate whether the web service is correctly deployed on the application server or not (if not, redeploy it) and also verify whether local host 9080 or the specified port is opened to accept the request or not.

Figure 13. Virtual host error during Web service call
Virtual Host error in a Web browser

Your investigation points should include the deployed directory structure in the application server. Verify whether WSDL and the generated XML mapping files contain all of the web service operations or not.

Check the ports setting by going into the admin console of the application server. Also verify whether the Java™ Enterprise Edition (JEE) deployment descriptors contain the application information or not.

You might need to verify the Java EE deployment descriptors for the web services project.

Publish failed with errors, warnings or both. Please see server logs for more details.

(GenerateDetails web service)

While publishing the web service, if you encounter "Error while publishing the WSDL," as shown in Figure 14, the software doesn't allow you to proceed further with publishing. Check the error details. In this case, the error message mentions that is not able to resolve the name. We often misinterpret this error by looking into the source of the directory where it was created. However, you need to verify that the Java™ file from which the web service is trying to resolve the name in order to publish. In this example, it is trying to find the file "" from web service project, which is missing from the web service project of Rational Application Developer. Placing the file in the project directory and republishing should resolve this error.

Web service publishing errors can also occur due to incorrect deployment descriptors. The chances of this are high if it is done manually or during a mismatched configuration at runtime.

Figure 14. Error while publishing the WSDL
WSDL Publishing failed error services.engine.deployment.wsdd.WSDDNonFatalException:

(GenerateDetails web service)

This kind of issue (it mostly happens while creating a web service the first time or after making changes in the web service classes which couldn't reflect the application server files properly), If you encounter it while using the web service, verify whether the file that this error mentions is present on the application server-deployed application path or not. If not, you need to redeploy the web service in the application server. It is clear from the screen image titled "Web service-generated classes" (Figure 15) that these files are not listed in the server's location as the error is reporting (errors as displayed in the SystemOut.log of WebSphere Application Server):

WSWS1002E: An error occurred while processing the
Web services deployment descriptor for module:
WebServiceProject.war with error:
Figure 15. Web service-generated classes
Web service runtime Generated Classes

Null serializer factory specified in the TypeMappingImpl.register method

(GenerateDetails web service)

This problem usually occurs when there is a problem in web service generation for a complex data type of object that, in turn, uses another object. The error description would look like this output (errors as displayed in the SystemOut.log of WebSphere Application Server):

WSWS1002E: An error occurred while processing the
Web services deployment descriptor for module:
WebServiceProject.war with error:
wsdd.WSDDException: javax.xml.rpc.JAXRPCException:
WSWS3218E: Error: Null serializer factory specified in
the TypeMappingImpl.register method.
javax.xml.rpc.JAXRPCException: WSWS3218E: Error:
Null serializer factory specified in the
TypeMappingImpl.register method.

Your basic investigation should also include the following steps:

  1. Verify that there are not any empty serialization and de serialization files created during web service deployment.
  2. If serialization and deserialization files are present, verify that the class attributes are present in those files.
  3. Verify from the WSDL file whether the complex object contains the reference of the object which it is using for the web service or not. During web service generation, it sometimes happens that, even though you have defined the complex object from the Java perspective, it doesn't get reflected properly in the WSDL.

If you are not able to see complex object details in the Web Services Explorer

(DisplayUnit web service)

It happens in some cases that even though you have defined the complex object structure clearly but not able to get the information when testing through the web service client.

Consider the following example, because it is clear from the screen image of the web service Explorer in Figure 16 that we are trying to invoke the getCustomerDetails web service method, which contains the address details. However, when we invoke that method, we are finding that the Address information is not coming up in the test client as it should be if the complex object is clearly defined. So we need to investigate the issue further.

Figure 16. Web service Explorer window
Web Service Explorer window

Rational Application Developer provides the WSDL mapping view, which you can find by double-clicking the WSDL file, as you can see in the WSDL view design mode (Figure 17).

Figure 17. WSDL in design mode
WSDL view in design mode

This illustration gives the complete information about all of the exposed operations of the web service. To verify whether a generated WSDL has a complex object attribute Address or not, follow these steps:

  1. Click getCustomerDetails to view the details. Because this method contains the Address class as defined in the Java file, the generated WSDL ideally should contain this.
  2. Click the arrow that is present on the right side of the method. It is clear from the "WSDL complex object attribute" screen (Figure 18) that the generated WSDL does not contain the object Address that is defined in the Customer class. This is the root cause of the problem. Therefore, you need to define the Address class in the generated WSDL and, once again, you need to republish the web service so that it can create the serialization and deserialization files for that object.
Figure 18. WSDL complex object attribute
screen segment: Customer class


From this article, you have learned several basic troubleshooting techniques that you can use with Rational Application Developer Version 7.5.4 error messages in a web service. This article can help you in quickly recognize the nature of the problem and can help you in debugging the weird issues that normally doesn't seems to appear at first time.



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

Zone=Rational, DevOps
ArticleTitle=Troubleshooting web service error messages