Support for IBM Mobile Foundation

Unless there are special instructions for a release of IBM Worklight, IBM MobileFirst Platform Foundation or IBM Mobile Foundation, assume that the below instructions apply to all releases.

Collecting this information before calling IBM support will help IBM understand the problem and save time analyzing the data.

MustGather for PMRs

The term "MustGather" represents the diagnostic data, which includes the system information, symptoms, log files, traces, and so on, that is required to resolve a problem. By collecting MustGather data early, even before you open a PMR, you help IBM Support quickly determine the following information:


Problems in Worklight, Mobile Foundation or Mobile Foundation can involve the following different parts:

  • Projects in Studio on a developer workstation
  • Application Center and Worklight, Mobile Foundation or Mobile Foundation Server on an Application Server or Bluemix
  • Applications running on client devices

It is important to collect the MustGather information from each part that is related to your problem. When in doubt, collect the MustGather information from all the parts.

If you are asked to collect additional logs while re-creating a problem, you may be asked to collect logs you have already collected again. This is to ensure that support can see the entire scope of the re-created problem across a set of matching logs.

The following information is some tips for collecting MustGather information that apply to any problem:

  • Describe the desired function, flows, and the error symptoms.
  • Describe when and what changes were made between the time when everything was working correctly and when the problem occurred.
  • Describe the simplest test case that reproduces the problem and provide the MustGather information for the test case.
  • Provide accurate and specific times for when the problem shows itself in the MustGather materials.
  • Describe how frequently the problem occurs and whether there are any triggering events for the problem.
  • Describe any temporary circumventions or repairs for the problem, such as restarting the server.
  • Describe the environment in which the problem occurs, including the versions of the components that are involved. Examples include client device, proxies, firewalls, Worklight server, application servers (including nodes and cells), databases, back-end servers, and so on.


In studio, navigate as follows:

  • On Windows: Help → About Eclipse → Installation Details
  • On macOS: Eclipse → About Eclipse → Installation Details

Provide the following information from the Installation Details:

From the Installed Software tab:

  • The version of Studio. You can find additional ways to find version information at Finding versions in IBM Worklight
  • The version of Eclipse. You will have to expand the Eclipse IDE for Java EE Developers to see the Eclipse version.

From the Configuration tab:
The version of the Java SDK or JRE that Studio is running under. Also include the operating system Studio is running under.

In addition, provide the following:

  • Describe any third-party libraries and versions that you are using. For example, jQuery Mobile, PhoneGap or Cordova plugins, and so on.
  • Collect an export of the project.
  • Collect the /.metadata/.log file.
  • For product releases before 6.0: Collect the files in the Eclipse_workspace/WorklightServerHome/project_name/log directory.
  • For product release 6.0 and later: Collect the files in the Eclipse_workspace/WorklightServerConfig/servers/worklight/logs directory.
  • Collect the Eclipse_workspace/WorklightServerConfig/servers/worklight/jvm.options file.
  • Collect the Eclipse_workspace/WorklightServerConfig/servers/worklight/server.xml file.


To collect the debug information to send to support, you can use the following steps for your platform to output the contents of the terminal to a file in the same directory.

  • MacOS and Linux: mfp COMMAND -d 2>&1|tee cliOuput.log
  • Windows:
    1. powershell
    2. mfp COMMAND -d 2>&1 | tee cliOutput.log
    3. exit

Note: The -dd flag is preferred, if it is available for the version being used.

Version Debug Flag Flag Description full command
6.2.0.0 -d, --debug debug mode produces verbose log output wl -d
6.2.0.1 -d, --debug debug mode produces verbose log output wl -d
6.3.0 -d, --debug debug mode produces verbose log output mfp -d
7.0.0 -d, --debug debug mode produces verbose log output mfp -d
7.1.0 -d, --debug debug mode produces verbose log output mfp -d
8.0.0 -d, --debug Debug mode produces debug log output mfpdev -d
8.0.0 -dd, --ddebug Debug mode produces verbose log output mfpdev -dd

Starting with iFix 20160413-1613 for 7.0.0, 20160413-1346 for 7.1.0, 8.0.0 and all later releases, the version and runtime environment for the server is stored in the topology.log file in the same directory as the other logs. If you are running an earlier version, you need to collect the following information manually:

  • Describe the version of Worklight Server or Worklight Application Center that you are using.
  • You can find the version by clicking on About in the Worklight/Operations Console.
  • You can find additional ways to find version information at Finding versions in IBM Worklight
  • Describe the application server and the version that you are using including the operating system on which it is running. For example, are you using the WebSphere Application Server Liberty profile, WebSphere Application Server, Tomcat, or another server?
  • Describe the Java SDK and version that you are using.
  • Describe the database type (example: DB2), version, connector version, connection properties and the database driver version.

If the problem occurs during the installation of Worklight Server with IBM Installation Manager , collect:

  • worklight_install_dir/failed-install.log
  • Installation_Manager_log_dir/worklight-install*.log
  • Installation_Manager_log_dir/worklight-uninstall*.log

The installation_manager_log_dir directory is typically in the following locations:

  • For a system-wide Installation Manager:
    • On UNIX-based operating systems: /var/ibm/InstallationManager/logs/
    • On Microsoft Windows 7 and 8 operating systems: C:\ProgramData\IBM\Installation Manager\logs\
    • On the Microsoft Windows XP operating system: C:\Documents and Settings\All Users\Application Data\IBM\Installation Manager\logs\
  • For a per-user Installation Manager:
    • On UNIX-based operating systems: $HOME/var/ibm/InstallationManager/logs/
    • On Microsoft Windows 7 and 8 operating systems: C:\Users\USER\AppData\Roaming\IBM\Installation Manager\logs\
    • On the Microsoft Windows XP operating system: C:\Documents and Settings\USER\Application Data\IBM\Installation Manager\logs\

If the performance impact to your environment is not too severe, you can collect the trace for *=info:com.ibm.mfp.*=all:com.worklight.*=all:com.ibm.worklight.*=all while recreating the problem.

Note: For Worklight 6.1 and earlier just use *=info:com.worklight.*=all

For instructions on enabling and collecting trace for WebSphere Application Server Liberty profile, see the Setting up trace and getting a full dump in the WebSphere Application Server V8.5 Liberty profile topic.

  • For Application Center add the following to the trace: com.ibm.puremeap.*=all
  • For Analytics add the following to the trace: com.ibm.mobile.analytics.*=all
  • For problems with push notifications for Worklight 6.2 to MobileFirst Platform Foundation 7.1, add the following to the trace: com.ibm.pushworks.server.*=all
  • For problems with push notifications for Mobile Foundation 8.0, add the following to the trace: com.ibm.mfp.push.server.*=all.
  • If the WebSphere Application Server Liberty profile was installed by the Worklight 5.x installer:
    • For Unix-based or Linux operating systems:
      • Collect the files in the /server/wlp/usr/servers/worklightServer/logs directory.
      • Collect the install_dir/server/wlp/usr/servers/worklightServer/server.xml file.
    • For Windows, look for the value of WLP_USER_DIR in the install_dir\server\wlp\etc\server.env file:
      • Collect the files in the WLP_USER_DIR\servers\worklightServer\logs directory.
      • Collect the WLP_USER_DIR\servers\worklightServer\server.xml file.
  • If the WebSphere Application Server Liberty profile was installed by the Liberty Installer:
    • For all platforms, look for the value of WLP_USER_DIR in the liberty_install_dir/etc/server.env file.
    • If there is not a value for WLP_USER_DIR, assume it has the liberty_install_dir/usr value.
      • Collect the files in the WLP_USER_DIR/servers/serverName/logs directory. If you are running in a server farm environment, collect the logs directory for each server.
      • Collect the WLP_USER_DIR/servers/serverName/server.xml file.
Note: You can automate the collection of files from WebSphere Application Server Liberty profile and their submission to IBM using the IBM Support Assistant Data Collector. For more information, see MustGather: Read first for WebSphere Application Server

If the performance impact to your environment is not too severe, you can collect the trace for *=info:com.ibm.mfp.*=all:com.worklight.*=all:com.ibm.worklight.*=all while recreating the problem.

Note: For Worklight 6.1 and earlier just use *=info:com.worklight.*=all

For instructions on enabling and collecting trace for WebSphere Application Server, see the Setting up a trace topic.

  • For Application Center add the following to the trace: com.ibm.puremeap.*=all
  • For Analytics add the following to the trace: com.ibm.mobile.analytics.*=all
  • For problems with push notifications for Worklight 6.2 to MobileFirst Platform Foundation 7.1, add the following to the trace: com.ibm.pushworks.server.*=all
  • For problems with push notifications for Mobile Foundation 8.0, add the following to the trace: com.ibm.mfp.push.server.*=all.
  • Collect the files and directories in the install_dir/profiles/server_profile/logs directory. If you are running in a server farm environment, collect the logs directory for each server.
  • Collect the files and directories in the install_dir/profiles/server_profile/config directory.
Note: You can automate the collection of files from WebSphere Application Server and their submission to IBM using the IBM Support Assistant Data Collector. For more information, see MustGather: Read first for WebSphere Application Server.
  • Collect the files and directories in the install_dir/logs directory. If you are running in a server farm environment, collect the logs directory for each server.
  • Collect the files and directories in the directory install_dir/conf directory.

If the problem occurs with the Server Configuration Tool (Worklight Server 6.1 and later), gather the following information:

  • For problems with the user interface of the Server Configuration Tool, collect the following configuration tool log file:
    • For UNIX-based operating systems: $HOME/.IBM/Worklight/configuration-tool-workspace/.metadata/.log
    • For Microsoft Windows 7 or 8 operating systems: C:\Users\user-name\AppData\Roaming\IBM\Worklight\configuration-tool-workspace\.metadata\.log
  • For problems with configuration actions that fail, such as install, update, uninstall, database, and so on, collect the log files that are associated with the execution of these actions. You can determine the location of the directory for the log files using File → Preferences → IBM Worklight Server Configuration Tool → Directory for configuration files. The default location is:
    • For UNIX-based operating systems: $HOME/.worklight/server-configuration-tool/
    • For Microsoft Windows 7 or 8 operating systems: C:\Users\user-name\Documents\IBM Worklight Server Data\Server Configuration Tool\. Inside this directory, the log files are stored in the logs/config-name/operation_timestamp_outcome.log files. Collect all the files in the logs/config-name folder, where config-name is the name of the configuration file with which you are having a problem.

If the client is a web browser, provide the following information:

  • Describe the client and browser version.
  • Open the debugger of the browser and copy the contents of the console to a file that you include in the MustGather materials.

If the client is a mobile device, describe the device, including:

  • Is it a physical device or emulator?
  • What is the make of the device? For example, Apple, Blackberry, Samsung, HTC or other device.
  • What is the model and version of the device?
  • What is the version of the operating system on the device?
    • On Apple iOS devices, click Settings → General → About → Version
    • On Google Android devices, click Settings → About phone → Software information → Android version
    • On BlackBerry 10 devices, click Settings → About phone → OS, Also, Settings → About phone → General displays additional information, such as the device model and model number
    • On Windows Phone devices, click Settings → About → More info
  • Is the device stock or has it been rooted?
  • Have you have tried multiple devices? Then, note the results for each device. For example, "It works on Apple iPhones that are running iOS 4 and Google Android that are phones running 3.0, but not on Android phones that are running 2.2."

Collect the logs from the client devices:

If you are using Worklight Mobile Foundation 6.2 or later, you can configure Worklight to dynamically control log entries made with the Worklight logging APIs on all client devices supported by Worklight. These log entries are created both by the Worklight platform and customer-developed applications that issue their own log entries through the Worklight logging API. You can also configure Worklight to automatically transfer the logs from client devices to the Worklight server where the log entries can be stored for later debugging. See Client-side log capture for details on how to create, control and capture Worklight client-side log entries.

If you are not using Client-side log capture (see the previous item) or you need to capture log entries issued outside of the Worklight logging APIs, you need to manually collect the log files from the client devices.

On the Google Android platform, capture the debug messages for the device by running the Android Debug Bridge (ADB) logcat command on a workstation that is attached to the device with a USB cable. ADB is included in the installation of the Android Developer Tools.

You can run the following command that is appropriate for your workstation from an command-line that is running in the platform-tools directory where the android SDK is installed.

Administrator/root privileges might be required to successfully run logcat.

  • For Microsoft Windows operating systems: adb.exe logcat -d -v time >logcat.txt
  • For Linux operating systems: ./adb logcat -d -v time>logcat.txt

Collect the logcat.txt file that is created as part of the MustGather materials.
You can find the documentation for logcat on the Android Developers site.

If you are using the Apple iOS platform, you can copy the log files using Xcode Organizer. To access the Organizer, navigate to Window → Organizer → Select Device in the Left Pane → Device Logs. Then, copy the device log files as part of the MustGather materials.

You can find additional information on collecting diagnostic information in the Debugging Deployed iOS Apps topic within the iOS Developer Library.


To diagnose or identify a problem, it is sometimes necessary to provide Technical Support with data and information from your system. In addition, Technical Support might also need to provide you with tools or utilities to be used in problem determination. You can submit files using one of following methods to help speed problem diagnosis:

  • Service Request (SR)
  • FTP to the Enhanced Customer Data Repository (ECuRep)

For information about using each of these services, see Exchanging information with IBM Technical Support.