IBM Support

z/OS Connect EE issues a 500 Internal Server Error when deploying an API with API Toolkit V3.0.6.0

Troubleshooting


Problem

After installing V3.0.6.0 of the z/OS Connect EE API Toolkit, and attempting to deploy an API, z/OS Connect EE issues a 500 Internal Server Error.


Symptom

Attempting to deploy an API causes z/OS Connect EE to issue a 500 internal server error. This error is displayed in both the API deployment result dialog, as well as the Problems view. API archive (.aar) files that are created from the API project will not install onto the z/OS Connect EE server.

Cause

Beginning with the release of V3.0.6.0 of the API Toolkit, a mapping.xml is generated for every operation in an API project. For existing projects, mapping.xml files will be generated if the API is edited. This file is not new, and represents the operation-specific usage of the associated service.
 
With the introduction of the multiple response codes capability, it became necessary to include <responseMessages> elements in the mapping.xml for each response to store the response code, user-supplied description, and rules for selecting the response in addition to the response mapping if it exists.  Previous versions of the API Toolkit did not include <responseMessages> elements for a response unless a mapping existed, as there could only be one response (200) whose description could not be customized by the user.
 
z/OS Connect EE server runtime versions prior to V3.0.16 contain a defect where it is assumed that all <responseMessages> have a response mapping (that is, using a child <mappingRootModel> element). If the API Toolkit version 3.0.6.0 or later is used to edit or create an API that does not have a response mappping on every operation, a NullPointerException will occur when attempting to deploy the API to server versions prior to 3.0.16, this is due to the presence of <responseMessages> without a child <mappingRootModel> in the mapping.xml.

Environment

z/OS

Diagnosing The Problem

In the API deployment result dialog, check for the following error message:

BAQR7033E: Internal server error.


In the Problems view, check for the following error message:
An error was received for z/OS Connect EE connection "your_server_name" (server_hostname:port): 500 Internal Server Error, BAQR7033E: Internal server error

The following message might also be written on start up of the z/OS Connect EE server:
CWWKE0701E:[com.ibm.zosconnect.internal.ApiManagerImpl(316)] The activate method has thrown an exception Bundle:com.ibm.zosconnect (id=119)  java.lang.NullPointerException

The following image demonstrates how these errors are recorded and displayed in the API deployment result dialog (top) & the Problems view (bottom):
500 Internal Server Error as shown in the API deployment result dialog (top), and the Problems view (bottom).


In addition to the previous errors, z/OS Connect EE server logs will contain the following Null Pointer Exception:
 CWWKE0701E:[com.ibm.zosconnect.internal.ApiManagerImpl(316)] The activate method has thrown an exception Bundle:com.ibm.zosconnect (id=119)  java.lang.NullPointerException 
and                        
java.lang.NullPointerException   at
com.ibm.zosconnect.internal.ApiManagerImpl.getMappingRoot(Unknown Source)    at
com.ibm.zosconnect.internal.ApiManagerImpl.processApiPackage(Unknown Source)    at
com.ibm.zosconnect.internal.ApiManagerImpl.installNewApiPackage(Unknown Source)    at
com.ibm.zosconnect.internal.ApiManagerImpl.installApiFromApiArchive(Unknown Source)    at
com.ibm.zosconnect.internal.web.ServiceProxyServlet$21.run(Unknown Source)    at
com.ibm.ws.webcontainer.async.ServiceWrapper.wrapAndRun(ServiceWrapper.java:209)    at
com.ibm.ws.webcontainer.async.ContextWrapper.run(ContextWrapper.java:29)    at
com.ibm.ws.webcontainer.async.WrapperRunnableImpl.run(WrapperRunnableImpl.java:84)    at
java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1160)    at
java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:635)    at
java.lang.Thread.run(Thread.java:812)

Resolving The Problem

Upgrade the z/OS Connect EE server runtime to version 3.0.16 or later.
 

If it is not feasible to immediately upgrade to the latest version of the server runtime, consider using one the following workarounds:

      

  1. Continue to use V3.0.6.0 of the API Toolkit, and create the appropriate response.map file needed for each API operation.

    • Do this for each API operation by selecting Mapping... -> Open response mapping in the API Editor. This must be done for every API operation that you edit or create with API Toolkit V3.0.6.0 or later.

      

  1. Roll back your installation of the API Toolkit to a version that is previous of V3.0.6.0.

    • Do this by selecting the Roll back option in the IBM Installation Manager, and following the guided menu prompts to revert the version of the API Toolkit to a version that is previous of V3.0.6.0.

       

Document information

More support for: z/OS Connect Enterprise Edition

Component: z/OS Connect EE API Toolkit V3.0.6.0

Software version: 3.0

Operating system(s): z/OS

Reference #: 0795584

Modified date: 25 February 2019