When using Safari Web Inspector to debug your Titanium iOS apps, see Debugging iOS Apps with 3rd-party Tools for details!


Titanium SDK enables Studio to initiate a debug session on an iOS device. Debugging on an iOS device involves the following steps:

This page will guide you through the setup, and the launch, of a debug session.

Debugging on iOS devices is only supported on macOS. You must already be set up to run applications on your iOS device, as documented in Deploying to iOS devices.


To debug on an iOS device, you must:

Each time you run the debugger, Studio builds the application and attempts to install it using iTunes. In order to install the application using iTunes, you must either:

For convenience, if you use iTunes for syncing applications to device, it is recommended that you configure iTunes to sync applications automatically.

As an alternative to the iTunes sync process, you may use Xcode or the iPhone Configuration Utility in order to install the application on the device once the Titanium build and deploy is done.

Network Setup

In order to debug on an iOS device, the device and computer running Studio must be attached to the same wireless (Wi-Fi) network, and the network must allow connections between two clients.

Some public Wi-Fi networks are configured so clients can only communicate with the internet, not with each other. These networks are not compatible with on-device debugging for iOS.

If you do not have a suitable Wi-Fi network available, you can create an ad-hoc network on your computer and connect to it using your device. See
macOS: Create a computer-to-computer network on the Apple Support site for directions on creating an ad-hoc network.

Launching a Debug Session

Before debugging, you must have created a Titanium project with an iPhone/iPad deploy target. There are three basic steps:

  1. Initiate the debug session in Studio.
  2. Wait while application builds and installs.
  3. Launch the application from the device and start debugging

Initiate the Debug Session

  1. Make sure your project is selected in the Project Explorer view.
  2. In the global tool bar, select Debug from the Launch Mode drop-down list.
  3. Select the iOS device you want to launch your project on or iTunes Sync to install the application to iTunes from the Target drop-down list.
  4. Click the Launch button.
  5. Complete the wizard to initiate a debug session. Studio prompts you to pick the certificate, provisioning profile, and SDK version to use for the debug build.

After you complete the wizard once, Studio creates a launch configuration for you, named Titanium iOS Device - <AppName>. You can select this launch configuration, after launching the Debug Configuration wizard by select Debug Configurations from the Target drop-down list, to skip the wizard and start a new debug session using the same parameters.

iTunes Deployment

If you chose to deploy your application to iTune first, you need to perform a few extra steps to install it to your device.  After Studio builds your project, the built application is deployed into iTunes. If you have already deployed this application to device, iTunes prompts you to replace the older application with the new version. iTunes syncs the new application to the connected device(s). 

Launch the Application and Debug

After the application finishes installing:

  1. Run the application on the device.
  2. A dialog appears on the device indicating it's waiting for the debug session to start on the indicated WiFi network.  Both the host computer and target iOS device must be on the same WiFi network in order to debug.  If they differ, you need to change either host computer's or target iOS device's WiFi settings to match the other's WiFi network.  You may need to cancel the debug session and restart the debug process.
  3. The device connects to Studio, and a debug session begins (and is visible in Studio's Debug perspective).

In the unlikely case that you have the same debug version of the application installed on two devices at the same time, and you launch them at the same time, Studio prompts you to select which version to debug.

Troubleshooting iOS On-Device Debugging Problems

iTunes Fails to Sync the Application to the Device After First Launch

Debugger Fails to Connect

Wi-Fi Sync Problems

You should be able to see the device in iTunes when it is not connected using the USB cable. If you can't, try the following:

Testing Network Connection

If you need to test whether your device and computer are on the same network, you can create a test web site in Studio to test the connection.

Related Topics