Troubleshooting Node.js applications

If you have a problem with a Node.js application, you can use the diagnostics that are provided by CICS® and Node.js to determine the cause of the problem.

CICS provides some statistics, messages, and tracing to help you diagnose problems that are related to Node.js. The diagnostic tools and interfaces that are provided with Node.js can give you more detailed information about the Node.js runtime and the execution of the application.

You can use freely available tools that perform real-time and offline analysis of a Node.js application, for example IBM® Health Center or Appmetrics. For more information, see IBM Monitoring and Diagnostic Tools - Health Center or Node Application Metrics.

For more information about where to find log files, see Controlling the location for NODEJSAPP output, logs and trace.

Important: If you cannot fix the cause of the problem, contact IBM support. Make sure that you provide the required information, as listed in the MustGather for reporting Node.js problems.

For troubleshooting information relating to the IBM SDK for Node.js -z/OS®, see IBM SDK for Node.js - z/OS Troubleshooting.

If the Installation Verification Program (IVP) fails to run:

  1. Check the MSGUSR log. CICS messages are written here when the CICS bundle and NODEJSAPP bundle part are installed and enabled.
  2. Check the SYSPRINT log. CICS messages are written here when the Node.js profile is processed.
  3. Check the WORK_DIR/APPLID/DFHJNIVP/IVPSAMPLE directory. Node.js runtime and application messages are written into the files CURRENT.STDOUT and CURRENT.STDERR. If CICS tracing is enabled, it is written to CURRENT.TRACE.

If the npm install fails to reach the site required to download Node.js application dependencies

You might see the error getaddrinfo ENOTFOUND nodejs.org nodejs.org:443.

  1. Check the messages returned by npm -verbose install for errors that identify the site TCP/IP address, for example Error: connect ETIMEDOUT 2400:cb00:2048:1::6812:5e60:443.
  2. Try using alternative TCP/IP addresses for the site. To list alternative TCP/IP IPv6 and IPv4 addresses, use command dig registry.npmjs.org -t any. To change npm to use a TCP/IP address, first use command npm adduser --registry=https://<ipaddress> and then retry command npm install.
  3. Contact your networking team to investigate the TCP/IP and firewall configuration.

If the NODEJSAPP disables immediately

If you receive the message CEE5207E The signal SIGABRT was received in stderr, you might have reached the limit for shared message queues on your LPAR. When Node.js applications are terminated by a SIGKILL signal, shared message queues might not be deallocated. To avoid this, you should ensure your applications terminate in a timely manner in response to a SIGTERM signal, for more information see Developing Node.js applications.

You can check the number of shared messages queues that use the z/OS console command D OMVS,L and look for IPCMSGNIDS. To delete shared message queues, use the ipcrm command, for more information, see ipcrm — Remove message queues, semaphore sets, or shared memory IDs.

If you receive a message like
  • CEE0374C CONDITION=CEE3561S TOKEN=00030DE9 59C3C5C5 00000000_00000001 WHILE RUNNING PROGRAM static-initial in the CICS job log,
  • CEE3501S The module libnode.so was not found in stderr,
  • or DFHSJ1313 E CICSUSER CNJL NODEJSAPP CICSJSON was disabled because an unsupported version of IBM SDK for Node.js - z/OS was used in MSGUSR
check if you're using the minimum level of Node.js supported in CICS. The path to the Node.js runtime is specified by the NODE_HOME option in the Node.js profile.