Troubleshoot the Web services gateway: WAS ND

Troubleshoot the Web services gateway

This topic provides hints to help you resolve problems you experience when using the Web services gateway.

Before you begin

For information on resolving WebSphere-level problems, see Diagnosing and fixing problems.

For current information available from IBM Support on known problems and their resolution, see the IBM Support page.

IBM Support has documents that can save you time gathering information needed to resolve this problem. Before opening a PMR, see the IBM Support "must gather" page.

If you report a gateway-related problem to IBM Service and Support, include the gateway release and build information that is listed under the About option of the Web services gateway administrative user interface.

What you need to know

To help you identify and resolve gateway-related problems, use the WebSphere Application Server trace and logging facilities. To enable trace for the gateway, set the appserver trace string to com.ibm.wsgw.*=all=enabled. If you encounter a problem that you think might be related to the gateway, you can check for error messages in the WebSphere Application Server administrative console, and in the appserver stdout.log file. You can also enable the appserver debug trace to provide a detailed exception dump.

The gateway administrative user interface uses cascading style sheets to lay out its pages, and Javascript to monitor progress and to advise you as you fill in each on-screen form. Your Web browser must therefore support Javascript and cascading style sheets, and it must be configured so that Javascript and style sheets are enabled. This configuration depends on which browser you use. For example for Netscape, you select Edit > Preferences, click Advanced in the Category pane, then confirm that the Enable Javascript and Enable style sheets check boxes are selected.

A list of the gateway run-time system messages, with details of what each message means, is provided in Web services gateway messages.

Here is a checklist of common problems:

You are about to install an upgraded gateway, but you do not want to lose your existing gateway configuration.

When you complete the installation of an upgraded gateway, any previously configured gateway is replaced with an upgraded but empty gateway. To preserve an existing gateway configuration, you need to save the configuration before you upgrade the gateway, then restore the configuration after the upgrade is installed. For detailed instructions see Preserving an existing gateway configuration.

You find that none of the options to change the gateway configuration are available from the gateway administrative user interface.

You are trying to modify a gateway that is part of a locked configuration load-balancing group. If you open the user interface for a locked configuration gateway, you are only offered options to list information about the configuration.

You export a gateway configuration, and you find that you cannot import it into a gateway running on IBM WebSphere Application Server V5.1.0.4. or later.

If you export a gateway that is running on a version of IBM WebSphere Application Server that is earlier than V5.1.0.4., and the exported gateway includes JMS channels among its deployed resources, then you need to modify the exported configuration file before you can import the saved configuration into a later version of the gateway. Open the exported configuration file, find the definition of the JMS channel external end point address and replace the property separator "&" with "&". For example here is the exported text (pre-V5.1.0.4.):

<ExternalEndPointAddress type="text">jms:/queue?destination=jms/SOAPJMSQueue1&connectionFactory=jms/SOAPJMSFactory1</ExternalEndPointAddress>
and here is the edited text (for import into V5.1.0.4. or later):

<ExternalEndPointAddress type="text">jms:/queue?destination=jms/SOAPJMSQueue1&connectionFactory=jms/SOAPJMSFactory1</ExternalEndPointAddress>

You deploy multiple gateway configurations within a single network deployment cell, and find that certain gateways within the cell are no longer available.

You cannot safely deploy multiple gateway configurations within a single network deployment cell.

If you are using the (deprecated) Apache SOAP channel, you cannot safely deploy multiple gateway configurations within a single network deployment cell.

You have managed to deploy your Web service in the Web services gateway but you are getting a class cast exception when you invoke the operation which takes an integer parameter.

Check that your client is using the version of the soap.jar file that is supplied in the WebSphere Application Server /AppServer/lib/app directory. If you enable trace, you can look in the trace for the request <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema">

The gateway expects the 2001 version of the XML schema. Older versions of the soap.jar file (including 2.2) generate 1999 schema. If you have the soap.jar file that is supplied with WebSphere Application Server in the client class path, you can see 2001 schema in the request.

The persistent state of the Web services gateway has become out of sync with the channel applications.

This mismatch can occur if you remove and reinstall the Apache SOAP channel applications. If this operation is necessary, then either verify that all corresponding channels configured with the Web services gateway are removed, or remove and reinstall the Web services gateway at the same time.
Note: The Web services gateway application (wsgw.ear) must be installed before the channel and filter applications. If the gateway application needs to be reinstalled, all channels and filters must be uninstalled first, then reinstalled after the gateway application.

You get listener port time out errors when large messages are passed using the synchronous SOAP over JMS channel.

As with any synchronous channel, time out errors can occur. To minimize the frequency of time out errors, increase the time out settings for the channel. If the problem persists, then disable trace and logging for the gateway (by setting the appserver trace string to com.ibm.wsgw.*=all=disabled).

You are getting SOAP fault messages, but cannot determine the precise problem from the fault message.

If you receive a SOAP fault message with a faultstring that is just the value of one of the parameters of the invocation, that means the parameter value is not valid. For example if you have a service that expects an int parameter and you send it a message containing the value "1.1", then the fault message you receive contains 1.1 as the fault string:

<faultcode>SOAP-ENV:Client</faultcode> <faultstring>1.1</faultstring>

This message is consistent with Apache SOAP behavior, and is not correctable by the gateway.

If you receive a SOAP fault message containing an element that is not present in the WSDL for the target service, then the error message thrown can be difficult to identify. There are two possible scenarios:

The WSDL is deployed to use Generic Classes. In this case the returned SOAP message contains an IllegalArgument exception. For example:

[Attributes={}] [faultCode=SOAP-ENV:Server] [faultString=com.ibm.wsgw.WSGWException: WSGW0043E: Exception while executing operation createEntry service ExchangeService. Exception: org.apache.wsif.WSIFException: SOAPException: SOAP-ENV:ClientNo mapping found for 'com.ibm.jrom.JROMValue' using encoding style 'http://schemas.xmlsoap.org/soap/encoding/'.; nested exception is: [SOAPException: faultCode=SOAP-ENV:Client; msg=No mapping found for 'com.ibm.jrom.JROMValue' using encoding style 'http://schemas.xmlsoap.org/soap/encoding/'.; targetException=java.lang.IllegalArgumentException: No mapping found for 'com.ibm.jrom.JROMValue' using encoding style 'http://schemas.xmlsoap.org/soap/encoding/'.]] [faultActorURI=/wsgwsoap1/soaprpcrouter] ...

The WSDL is deployed to use Deployed Classes. In this case an empty message is returned. For example:

[Attributes={}] [faultCode=null] [faultString=null] [faultActorURI=null] [DetailEntries=] [FaultEntries=]

These messages are consistent with Apache SOAP behavior, and are not correctable by the gateway.

When you are specifying the security settings that are applied between the service requester (the client) and the gateway, you set Identification to Digital Signature. When you click Apply Changes, the following "AuthMethod signature is not valid" error message is displayed:

WSGW0009E: Failed to deploy service. Exception: Error change service properties: com.ibm.wsspi.wssecurity.SoapSecurityException: WSEC0105E: LoginConfig: AuthMethod Signature is not valid.

This problem only occurs when you set Identification to Digital Signature. The problem is caused by a mismatch between the request bindings and the response bindings. For example, you might have set Request Sender signing information on the request bindings instead of Request Receiver, or Response Receiver on the response bindings instead of Response Sender. To fix the problem, set matching request and response bindings. For instructions on setting these parameters, see

Request receiver binding collection

Response sender binding collection

Request sender binding collection

Response receiver binding collection

When you run secured Web services through a Web services gateway using LTPA authentication with a certificate store defined, an "Unable to build a valid CertPath" error similar to the following is displayed:

[10/23/03 12:31:40:393 CDT] 78a54799 enterprise I com.ibm.ws.webservices.engine.enterprise TRAS0014I: The following exception was logged WebServicesFault faultCode: {http://schemas.xmlsoap.org/ws/2003/06/secext}InvalidSecurityToken faultString: WSEC5085E: Unable to build a valid CertPath: java.security.cert.CertPathBuilderException: PKIXCertPathBuilderImpl could not build a valid CertPath.; internal cause is: java.security.cert.CertPathValidatorException: The certificate issued by CN=Int CA2, OU=TRL, O=IBM, ST=Kanagawa, C=JP is not trusted; internal cause is: java.security.cert.CertPathValidatorException: Certificate chaining error

This problem occurs when one of the defined certificate stores on the Web services gateway administrative client is missing the certificate path.

To correct this problem,

Add the certificate path to the certificate store configuration. For example, if you are using the sample certificate store from WebSphere Application Server, the path is:

X509 Certificate Path: /usr/WebSphere/AppServer/etc/ws-security/samples/intca2.cer

Run the client again.

When you run secured Web services through the Web services gateway, a "Failed authentication" error similar to the following is displayed:

[10/3/03 21:35:48:597 CDT] 33c558 enterprise I com.ibm.ws.webservices.engine.enterprise TRAS0014I: The following exception was logged WebServicesFault faultCode: {http://schemas.xmlsoap.org/ws/2003/06/secext}FailedAuthentication faultString: WSEC5078E: Login failed: javax.security.auth.login.LoginException: java.lang.NullPointerException at com.ibm.wsspi.wssecurity.auth.module.WSSecurityMappingModule._login(WSSecur ityMappingModule.java:152)

The problem occurs when the Web services gateway does not enable global security and there is no LDAP user registry information to authenticate the incoming user login.

To correct this problem, enable global security on the Web services gateway appserver using the same LDAP user registry that the deployment manager uses. See Enabling gateway-level authentication for more information.
Note: Before enabling global security on the Web services gateway, you need to uninstall the Web services gateway channels and applications, then re-install them after security is enabled.

When you run secured Web services through the Web services gateway, a "Failed login" error similar to the following is displayed:

WSEC5078E: Login failed: com.ibm.websphere.security.auth.WSLoginFailedException: AuthenLoginModule: Authentication failed reason = 2

This problem occurs when single sign-on is enabled and the same password is used on both the deployment manager and the Web services gateway appserver. The login fails even though the deployment manager and the Web services gateway appserver are both enabled with security, with the same LDAP user registry and with the same LTPA password. The problem occurs because the key that is generated and passed between the services is randomly generated, and is therefore different for each server even though the same password is used.

To correct this problem, export the key from one cell then import it into another.

You are enabling operation-level authorization, but when you install wsgwauth.ear, an error message appears in the WebSphere Application Server administrative console detailing a Java Naming and Directory Interface (JNDI) problem.

Check that you entered, in the "EJB References" for the authorization session bean, the correct JNDI name of the imported Web service enterprise bean. Note that this home is case sensitive.

You get JNDI lookup errors when you use the same names for JMS messaging queues and queue connection factories that run on appservers on different machines.

You should not use the same names for messaging queues and queue connection factories that run on appservers on different machines, because the Web Services Invocation Framework (WSIF) (which the gateway uses for service invocation) always looks first for JMS destinations locally, and only uses the full JNDI reference if it cannot find the destination locally. If you deploy to the gateway a Web service that is hosted on a remote machine, and the same names are used for messaging queues and queue connection factories on the remote machine and on the machine on which the gateway is hosted, then WSIF finds and uses the local queues even if the remote JNDI destination is provided in full in the WSDL service definition.

You are trying to have a Web services gateway send a SOAP/HTTPS message to another Web services gateway, and you are receiving a Malformed URLException error.

The Web services gateway can invoke Web services that include https:// in their addresses, if the Java and WebSphere security properties are configured accordingly. To check your security property settings, see the topic Invoking Web services over HTTPS

You clear 'Authorization Policy - Control access to this service' from the deployment details for a Web service, and you find the service no longer works.

A number of tasks are required to disable security. Clearing the check box for 'Authorization Policy - Control access to this service' still leaves WebSphere Application Server security in place, so basic authentication might still be required.

To disable security fully, use the WebSphere Application Server administrative console Security Center to disable Global Security.

You experience problems with handling Document style SOAP messages.

If you are using the Apache SOAP channel, then the SOAP message format must be RPC style. To handle Document style SOAP messages, use the SOAP over HTTP channel (which supports both RPC style and Document style SOAP messages).

You experience problems with handling SOAP messages with attachments.

To handle SOAP messages with attachments, use the SOAP over HTTP channel.

You experience problems with a Web service that uses complex data types. The same service works fine, when not using the gateway.

You need to do one of two things to support Web services that use complex types in the Web services gateway:

Set the message part representation for the service to Generic classes.

Set the message part representation for the service to Deployed Java classes, and make the original classes available to the appserver (either by updating the class path or by putting the JAR file somewhere like install_root/lib/app, where install_root is the root directory for your installation of IBM WebSphere Application Server). If you do not have the original classes, you can use wsdl2java to generate Java applications that can contain values of the complex type for the service, then compile the beans into a JAR file and make this file available to the appserver.

For more information on the factors to consider when choosing between these options, see Data type representation - Choosing between Generic classes and Deployed Java classes.

Note:

If your Web service has non-bean parameters (that is, it requires a custom serializer and deserializer) then it is not supported by the current release of the gateway.

Not all complex types that are expressible in XML schema are supported by the current release of the gateway. For more information, see Web services gateway - Supported types.

See also Complex data types - mapping namespaces to packages.

Enabling Web services through the Web services gateway