Resolving problems when starting an integration node

Use the advice given here to help you to resolve common problems that can arise when you start an integration node.

About this task

When you start an integration node by using the mqsistart command, the mqsicvp command is run automatically to check that the environment is set up correctly (for example, the installed level of Java™ is supported). On Linux® and UNIX, the mqsicvp command also verifies that the ODBC environment (if specified) is configured correctly. For more information, see mqsicvp command.

For advice about specific problems that can occur when you start an integration node, see the following sections.

The integration node fails to start because there is not enough space in the Java TMPDIR directory or access permissions for the Java TMPDIR directory are inadequate

Procedure

  • Scenario: The integration node fails to start and either an error message indicates that insufficient space is available or a BIP4512 exception indicates a java.lang.NoClassDefFoundError in the stack trace.
  • Explanation: This error has two possible causes:
    • The integration node uses Java JAR files. When the integration node starts, the Java runtime environment extracts the JAR files into a temporary directory, Java TMPDIR. On Linux, and UNIX computers, the TMPDIR directory is typically /tmp; on Windows computers, it is c:\temp. If this directory is not large enough to hold the JAR files, the integration node does not start.
    • If the program is packaged as a PAR file, the user must have access to the system temporary directory and adequate space must be available in the temporary directory.
  • Solution: Use one of the following methods to specify the location of this temporary JAR directory:
    • Use the environment variable TMPDIR.
    • Set the system property java.io.tmpdir.
    Allow at least 50 MB of space per integration server in this directory for IBM® App Connect Enterprise components. You might need more space if you deploy large user-defined nodes or other JARs to the integration node. You should ensure that all the dependencies of the compute node class are deployed to the integration node.

Error message BIP2228 is issued when you try to start a second integration node on Linux or UNIX

Procedure

  • Scenario: Error message BIP2228, which mentions semctl in the syslog, is displayed when you try to start a second integration node on Linux or UNIX.
  • Explanation: This error typically indicates a permissions problem with a semaphore used by IBM App Connect Enterprise. A semaphore is created when the first integration node starts after a reboot (or after an initial installation), and only members of the primary group of the semaphore creator can access this semaphore. This problem is a consequence of the UNIX System V IPC primitives that are used by IBM App Connect Enterprise.

    The BIP2228 message is logged by any integration node that is started by a user who is not a member of the primary group of the semaphore creator. The integration node tries to access the semaphore, but fails with a permissions-related error. The integration node then terminates with the BIP2228 message.

  • Solution: Avoid this problem by ensuring that all user IDs used to start IBM App Connect Enterprise have the same primary group. If this action is impractical, ensure that all user IDs are members of primary groups of all other user IDs. Contact your IBM Support Center for further assistance.

MQIsdp client connection is refused by the integration node

Procedure

  • Scenario: When a new MQIsdp client tries to connect to the integration node, its connection is refused.
  • Explanation: MQIsdp Client ID fields must be unique. If a client sends a CONN packet that contains the same Client ID as a currently connected client, the behavior is undefined.
  • Solution: Ensure that Client IDs are unique.

When you start the integration node through the DataFlowEngine, it cycles continually

Procedure

  • Scenario: When you start the integration node through the DataFlowEngine, it continually cycles, starts and stops, and errors BIP2801 and BIP2110 appear in the log: 
    Unable to load implementation file '/opt/IBM/DistHu b/v2/lib/libdhbNBIO.so',  rc=The file access permissions do not allow the specified action.
IBMibm Integration Bus internal program error.
  • Explanation: The permissions on /opt/IBM have a value of 700, meaning that the integration node service user ID cannot read the disthub files.
  • Solution: Set the permissions on /opt/IBM to 755, which is rwxr-xr-x.

The Java installation is at an incorrect level

Procedure

  • Scenario: You issue the command to start an integration node , but the integration node does not start and the system log includes message BIP8892, for example: 
    Verification failed. The installed Java level 1.3.2 does not 
   meet the required Java level 1.5.
  • Explanation: The command performs a check on the level of the Java product installed on the computer to ensure that the Java product is at the required level.
    The check has failed, therefore the integration node is not started.
  • Solution:
    • On distributed systems, you must use the JVM that is supplied with IBM App Connect Enterprise; no other Java product is supported. Check that you have run mqsiprofile, or (on Windows only) that you issued the mqsistart command from the correct command console.

      If you ran the profile command, check the settings of the environment variables in mqsiprofile; MQSI_JREPATH, PATH, and the appropriate library path environment variables for your operating system. Change these settings to point to the integrated JVM, and ensure that no other Java installation is in the path.

Error message BIP8875 is issued when you start an integration node

Procedure

  • Scenario: You issue the mqsistart command to start an integration node, but the integration node does not start and the system log shows message BIP8875, for example: 
    The component verification for INODE has finished, 
but one or more checks failed.
  • Explanation: The command performs a series of checks to ensure that the integration node environment, IBM MQ queues, and Java are correct and accessible.
    One or more of the checks for the integration node identified in the message has failed, therefore the integration node is not started.
  • Solution: Look in the system log, or in the Application log in the Event Viewer on Windows.
    Additional messages have been written before this message to indicate which checks have failed. All the checks are performed every time you issue mqsistart, therefore all errors are included in the log. Some messages are also returned when you run the command from the command line.

    Investigate the one or more errors that have been reported and check return codes and additional details. Look at the complete message content to check for typical causes of the error, and follow the advice given for the messages that you see in the log. View the complete message text in the Diagnostic Messages reference topics.

    For example, you might see one or more of the following messages:

    • BIP8875W: The component verification for 'component_name' has finished, but one or more checks failed.
    • BIP8877W: The environment verification for component 'component_name' has finished, but one or more checks failed.
    • BIP8883W: The IBM MQ verification for component 'component_name' has finished, but one or more checks failed.
    • BIP8885E: Verification failed. Failed to connect to queue manager 'queue_manager_name'. MQRC: return_code MQCC: completion_code
    • BIP8887E: Verification failed for queue 'queue_name' on queue manager 'queue_manager_name' while issuing 'operation'. MQRC: return_code MQCC: completion_code
    • BIP8888E: Verification failed. Failed to disconnect from queue manager 'queue_manager_name'. MQRC: return_code MQCC: completion_code
    • BIP8892E: Verification failed. The installed Java level 'level_installed' does not meet the required Java level 'level_supported'.
    • BIP8893E: Verification failed for environment variable 'variable_name'. Unable to access file 'file_name' with user ID 'user_ID'. Additional information for IBM support: data1 data2.
    • BIP8895E: Verification failed. Environment variable 'variable_name' is incorrect or missing.
    • BIP8896E: Verification failed. Unable to access the registry with user ID 'user_ID'. Additional information for IBM support: data1 data2
    • BIP8897E: Verification failed. Environment variable 'variable_name' does not match the component name 'component_name'.
    • BIP8903E: Verification failed. The APF Authorization check failed for file 'file_name'.
    • BIP8904E: Verification failed. Failed to start file 'file_name' with return code 'return_code' and errno 'error_number'.

    If you cannot resolve the problems that are reported, and you receive a message such as BIP8893 that includes additional information, include these items in the information that you provide when you contact IBM Service.

Warning messages BIP8288-BIP8297 are shown in the syslog when you start an integration node

Procedure

  • Scenario: Warning messages BIP8288-BIP8297 are shown in the syslog when you start an integration node on Linux and UNIX systems.
  • Explanation: One or more problems were detected with the ODBC environment on Linux and UNIX systems.
    When you start an integration node by using the mqsistart command, the mqsicvp command is run automatically to check that the integration node environment is set up correctly. On Linux and UNIX systems, this command also verifies that the ODBC environment is configured correctly. Warning messages are written to the syslog in the following situations:
    • The file that is referenced by the ODBCINI environment variable does not exist, or the integration node does not have access to read or write to the file.
    • The ODBCSYSINI environment variable is not set.
    • The directory that is referenced by the ODBCSYSINI environment variable does not contain a file called odbcinst.ini, or the integration node does not have access to read or write to the file.
    • The IE02_PATH is not set.
  • Solution: Examine the warning messages in the syslog. To view more information, run the mqsicvp command from the command line.

Error messages AMQ7626 and BIP8048 are displayed when you try to start an integration node

Procedure

  • Explanation: You see these messages when using an integration node on a queue manager that is configured for global coordination with Oracle.
  • Solution: Start the queue manager manually with the -si flag before starting the integration node.

Error messages BIP8048 and BIP8059 are displayed when you try to start an integration node

Procedure

  • Explanation: You see these messages when starting an integration node that does not have an associated queue manager, or the queue manager is not started.
  • Solution: If you do not have a queue manager associated with the integration node, create it. Start the queue manager by using the strmqm command, and then start the integration node.