MFT general troubleshooting

Use the following reference information to help you to diagnose errors in Managed File Transfer:

• Hints and tips for using MFT
  Here are some suggestions to help you to make best use of Managed File Transfer.
• Running trace on MFT
  We can use the methods described in this section to trace Managed File Transfer.
• Common MFT problems
  Common problems that might occur in your Managed File Transfer network.
• What to do if your MFT agent is not listed by the fteListAgents command
  If your agent is not listed by the fteListAgents command or is not displayed in the IBM MQ Explorer, or your file transfers are not displayed in the Transfer Log of the IBM MQ Explorer, we can carry out a number of problem determination steps to investigate the cause.
• What to do if your MFT agent process disappears but no diagnostic information is logged
  On UNIX platforms, if an agent process has disappeared but the agent log files do not contain any explanation, this might be caused by the way the agent has been started.
• What to do if the fteListAgents command shows an agent status of UNREACHABLE
  Your agent is running and responds successfully to the ftePingAgent command, and files are being transferred normally, but the agent is listed as UNREACHABLE by the fteListAgents command.
• What to do if the fteListAgents command shows an agent status of UNKNOWN
  You used the fteListAgents command to list the agents that are registered with a coordination queue manager or the fteShowAgentDetails command to display the information about an agent. The agent status is shown as UNKNOWN.
• What to do if ftePingAgent times out and reports a BFGCL0214I message
  ftePingAgent is a useful command-line utility provided with the IBM MQ Managed File Transfer component that enables you check whether an agent is currently running.
• What to do if your MFT agent or logger configuration is not secure
  If a Managed File Transfer process detects a condition that a configuration file contains sensitive information, is a keystore or truststore file, and has system-wide read, write, or delete permissions, the process will fail to start if detected at startup time. If the condition was not detected at startup time but was detected at runtime, Managed File Transfer generates a warning message and ignores the contents of the configuration file. This is relevant to the protocol bridge and the Connect:Direct bridge capabilities which reload a configuration if it changes while the agent is running.
• What to do if your transfer does not complete
  If your transfer does not complete we can carry out a number of problem determination steps to investigate the cause.
• What to do if you think that your file transfer is stuck
  On a heavily loaded system or when there are network problems between the source and destination agents, transfers can occasionally appear to be stuck in a queued or recovering state. There are a number of factors that can cause this.
• What to do if your scheduled file transfer does not run or is delayed
  If we have a scheduled transfer that does not run when it is due or is delayed, it might be because the agent is processing commands on its command queue. Because the agent is busy, scheduled transfers are not checked and are therefore not run.
• What to do if your protocol bridge agent reports that a file is not found
  When the protocol bridge agent reports that the SFTP or FTP server that the protocol bridge connects to returns a File not found error message, this message can mean that one of a number of different error cases has occurred.
• What to do if your MFT directory resource monitor is not triggering files
  A directory resource monitor polls a directory for files that match a trigger specification. For each file that matches the trigger specification, a transfer request is generated to the agent. When the request is submitted, the triggering file is ignored until the file is changed.
• What to do if destination files created by a transfer started by a queue resource monitor contain the wrong data
  We can create a resource monitor to monitor a queue and transfer a message or a group of messages on a queue to a file. The file name can be specified by using the MQMD message descriptors on the message or the first message in a group. If a message-to-file transfer fails and the message or group is left on the queue, the next time the monitor is triggered it might result in files being created that contain the wrong data.
• What to do if the destination queue is a clustered queue, or an alias to a clustered queue
  When using Managed File Transfer to transfer a file into a queue, if we use a destination that is a clustered queue, or an alias to a clustered queue, you get reason code 2085, or 2082. From Version 7.5.0, Fix Pack 4 onwards, this issue is resolved if you set the property enableClusterQueueInputOutput to true.
• What to do if messages are building up on your SYSTEM.MANAGED.DURABLE queues or filling your file system
  If the IBM MQ Explorer plug-in uses a durable subscription on the coordination queue manager, messages can build up on the SYSTEM.MANAGED.DURABLE queues. If we have a high-volume Managed File Transfer network, use the IBM MQ Explorer plug-in infrequently, or both, this message data can fill the local file system.
• Examining messages before publication
  Because agents can connect to IBM WebSphere MQ Version 6.0 queue managers, agents do not use the direct publication approach introduced in IBM WebSphere MQ Version 7.0. Instead, agents send ordinary messages to the coordination queue manager that contain an MQRFH header. The MQRFH header requests that the message's payload is published. These messages are sent to the SYSTEM.FTE queue on the coordination queue manager, and the messages are typically published immediately from that queue. If error conditions stop this publication, we can examine the messages on the queue before publication is attempted to help with diagnosis. We can do this by completing these following steps:
• Possible errors when transferring IBM i save files
  If we use Managed File Transfer to transfer the same IBM i save file several times, the transfer might fail.
• Possible errors when configuring the Redistributable MFT Agent
  Error messages when we are configuring the Redistributable Managed File Transfer Agent
• Guidance for using UAC and virtual store with MFT
  User Account Control (UAC) is present in Windows Server 2008 R2 and other similar operating systems. This is a security infrastructure and one of its features is to divert user data stored in the central Program Files directory to a user location, which is known as virtual store.
• Guidance for running an MFT agent or logger as a Windows service
  We can run a Managed File Transfer agent, a stand-alone database logger, and a stand-alone file logger, as Windows services. If we are having a problem with these Windows services, we can use the service log files and the information in this topic to diagnose the issue.
• Guidance for updating agent or logger JVM options
  If we use the -serviceJVMOptions parameter of the fteModifyAgent or fteModifyLogger command to modify an existing Windows Service definition for an agent or logger by updating, adding, or removing Java system properties, the existing Windows Service is first deleted before a new one is created in its place, and the agent or logger properties file is updated with the properties for the new Windows Service. The new Windows Service definition must be consistent with the updated Windows Service properties that are defined in the agent or logger properties file.
• Guidance for configuring an MFT resource monitor to avoid overloading an agent
  We can configure the property and parameter values of a Managed File Transfer resource monitor to reduce the load on an agent. Reducing the load on the agent improves the performance of that agent. There are several settings we can use, and you may need to use trial and error to find the best settings for the system configuration.
• What to do if variable substitution causes multiple files to go to a single file name
  For Managed File Transfer, if we are monitoring a directory and transferring multiple files from a source to a destination location and we are using ${FileName} variable substitution, we must test the variable substitution results. The results need to be tested because the use of variable substitution might cause unexpected combinations of file transfer commands to be invoked.
• What to do if you receive an error when updating your MFT database schema on an Oracle database
  We might receive the following error message when updating your database schema to the latest level by using the ftelog_tables_oracle_702_703.sql file: ERROR at line 1: ORA-02289: sequence does not exist. This error occurs because the sequences and triggers used by the tables are not in the same schema as the tables.
• MFT logger error handling and rejection
  The Managed File Transfer logger identifies two types of error: per-message errors and general errors.
• What to do if the MFT logger is started, but no transfer information is being logged to the database
  The database tables used by the Managed File Transfer logger require the database to have a page size of 8 KB or larger. If the page size of the database is not large enough, the tables are not created properly and you see the error SQLSTATE=42704.
• What to do if MFT does not read keystore properties from the keystore configuration file in AMS
  The keystore configuration file location, if not present in the default location, must be specified by the MQS_KEYSTORE_CONF variable in order for the Java AMS to run in client mode. If the location is not specified, the Managed File Transfer Agent logs will show the error message: "Failed to read keystore properties from the keystore configuration file."
• What to do if your MFT agent ABENDS with a java.lang.OutOfMemoryError due to native memory exhaustion
  While processing a number of managed transfer requests, such as file-to-file, message-to-file or file-to-message transfers, the agent abnormally ends (ABENDS) reporting a java.lang.OutOfMemoryError, and at the time your total RAM memory was not fully utilized. This exception has been caused by native memory exhaustion.
• BFGSS0023E errors and how to avoid them
  If you uninstall a Fix Pack from an installation in order to move back to a previous version of the product, and an agent associated with the installation was involved with managed transfers at the time the uninstallation took place, then that agent cannot start and will report an BFGSS0023E error. We can avoid this error by completing a number of steps that should prevent BFGSS0023E messages from appearing when the agents are restarted.
• What to do if managed transfers fail with BFGIO0341E errors
  If a managed transfer is transferring a file into a location that is being monitored by an external process, then it is possible for that managed transfer to fail with the error: BFGIO0341E: The rename of temporary file destination_filename.part to destination_filename failed because the temporary file does not exist. This is due to the way that the destination agent for managed transfers uses temporary files when writing a destination file.
• Return codes for MFT
  Managed File Transfer commands, Ant tasks, and log messages provide return codes to indicate whether functions have successfully completed.

Parent topic: Troubleshooting Managed File Transfer