Skip to content →

FAQs

General

Localhost traffic doesn't appear in Charles

Some systems are hard coded to not use proxies for localhost traffic. Specifically IE 7 and .Net applications have this feature.

The workaround is to connect to http://localhost./test/ instead (note the . after localhost). This should work identically to localhost normally but with the advantage that it will go through Charles.

Alternatively you can replace localhost with the name of your machine, or your local link IP address (eg. 192.168.1.2). So rather than connecting to http://localhost/test/ you connect to http://machinename/test/

Permalink

Strange characters appear in the response

Please check that the character encoding or charset is correctly set by the server, otherwise Charles will guess and may not guess correctly.

You may also need to choose a font that can display the charset in the response. You can change the font used in the Preferences on the User Interface tab. You will need to restart Charles for those changes to take effect.

Permalink

Charles won't start with "Failed to find Java VM"

Charles uses Java so you need to have a Java Runtime Environment installed. You can download Java from Oracle.

If you are using the 32 bit version of Charles you must have a 32 bit JRE installed, and vice versa if you're using the 64 bit version of Charles you must have a 64 bit JRE installed.

If you have the correct JRE installed and you still get a "Failed to find Java VM" message, please try reinstalling Java – if Charles can't find your JRE then it is likely that your registry contains some invalid details, which reinstalling will correct. Also note that Charles requires a JRE and will not run if you only have the JDK installed. When you install the JDK it will offer to install a JRE as well, so this is usually not an issue.

Permalink

Can no longer browse without Charles running

It is likely that your browser’s proxy settings have been changed to use Charles and then, for some reason, not changed back.

First try starting and quiting Charles normally to see if that corrects the problem. Because if Charles is stopped abnormally (such as a crash) it doesn’t have an opportunity to reset your proxy settings. It should notice that when it is restarted.

If that doesn’t work you’ll need to fix your proxy settings manually. How you do this depends on what application is misconfigured:

Windows / Internet Explorer
First quit Charles. Then go to the Internet Options in your Control Panel. Go to the Connections tab. Click on the LAN Settings. You’ll see a Proxy panel. Uncheck the Use a Proxy checkbox. Click OK until you’ve closed the Internet Options.

Mac OS X
Go to your System Preferences. Open the Network preferences. Choose the appropriate Network Port (you may need to reconfigure more than one if you have more than one) and click Configure. Go to the Proxies tab. Look in the list of proxy servers, you will see that Web Proxy and Secure Web Proxy are active. Uncheck those or reconfigure them as required for your network. Click Apply Now and then close the Network preferences.

Firefox
First quit Charles. Then go to the Firefox Preferences window, General tab, click Connection Settings. Then choose “Direct Connection to the Internet” or enter whatever proxy settings are required for your network. Click OK and then close the Preferences window.

Permalink

Charles crashes

Crashes are fortunately unusual! There are a few things that might be causing it, or will help me diagnose and hopefully fix the problem...

Known Problems

Below is a list of problems that I know about with Charles that you might be having, and the recommended solution:

NOD32 IMON

If you’re running the NOD32 antivirus package and have its IMON service running, you are likely to encounter crashes in Charles – one moment Charles will be running normally and the next it will have just disappeared, leaving your browser broken as it hasn’t corrected your proxy settings (fortunately restarting Charles will remedy that).

There is no fix from NOD32 at this time, so you need to either disable IMON or exclude Charles from it. The later being the preferred option as you continue to benefit from IMON – although you may also find that it interferes with other applications.

Excluding Charles from IMON
We need to add Charles to the exclusions list in order to exclude Charles. Charles is a Java application, so adding the Charles.exe application to the exclusions won’t help: instead you need to add the Charles.exe inside the launch4j-tmp directory in your JRE directory.

Open the NOD32 Control Centre, click on IMON, click on the Setup button to enter IMON Setup.

Go to the Miscellaneous tab and look for the Exclusion panel. Click the Edit... button in the Exclusion panel. The Exclude applications dialog will appear.

Click the Add... button. Find your Java installation. This is probably in C:Program FilesJavajre* where the * is a version number. If you have multiple JREs installed check which version Charles is using (use About Java in the Help menu). Inside the JRE folder will be a launch4j-tmp folder, in which will be the Charles.exe that you need to exclude.

Reporting A Crash

If your problem isn’t describe above then please report it to me. What will be a great starting point is if you can send:

  • Your OS name and version (eg. Windows XP SP2)
  • The version of Java that you’re running Charles in, as reported by the About Java option in the Help Menu
  • Look for any Java crash logs that have been created in the Charles directory (eg. C:Program FilesCharles), they will be named hs_err_pid###.log. Please copy and paste one of these into the email.

Finally send all of that to me using the Contact page.

Permalink

Can't authenticate through NTLM / Windows Integerated Authentication

Charles supports NTLM authenticating websites. You can access NTLM authenticating websites through Charles without any problems.

NTLM authentication is also known as “Windows NT Challenge Response” and “Integrated Windows Authentication” and is mainly used in conjunction with IIS.

NOTE You have to use HTTP 1.1 in order to use NTLM authentication through Charles. See more information on configuring your web browser to use HTTP 1.1

Permalink

Adobe Flash isn't using Charles on Mac OS X

Unfortunately there is a problem with Flash on Mac OS X. It does not use the OS proxy settings and does not appear to offer any proxy settings of its own. Therefore when you run Flash movies in the authoring environment or stand-alone they do not use Charles.

However, if you run your Flash movie in a browser it will use the correct proxy settings and use Charles.

A possible workaround for this problem is to use the Reverse Proxy feature of Charles so that you can make the URL you connect to actually pass through Charles (eg. http://localhost:12345/).

Permalink

Resource temporarily unavailable error on Windows Vista

If you see the following error message when you’re trying to use Charles:

Resource temporarily unavailable: recv failed
Try turning off “Parental Controls” on your account to allow Charles to run.

Permalink

Charles runs out of memory

After recording for a while Charles will run low on available memory. To free up memory you should clear the current session.

If you frequently run out of memory you can increase the default heap size.

Windows

Edit C:Program FilesCharlesCharles.ini and change vm.heapsize.preferred to a higher number. Be sure not to remove any other the letters or symbols around the numbers!

Mac OS X

Find Charles.app in your Applications folder, right click and choose Show Package Contents. Open the Contents folder and open Info.plist in a text editor, such as Text Edit. Find VMOptions and change the number in -Xmx256m. Be sure not to remove any other the letters or symbols around the numbers!

Linux

Edit the charles.sh file and change the number in -Xmx256m. Be sure not to remove any other the letters or symbols around the numbers!

Permalink

VPN not working with Charles

Try logging off and back into the VPN after running Charles for the VPN software to pick up the proxy settings change.

Permalink

Running multiple instances of Charles

If you need to run multiple instances of Charles on a single Windows machine, such as in a Citrix environment, you need to make a few changes to how you use Charles.

In the Charles folder in Program Files, edit the Charles.ini file and remove the "single.instance=dde" line, then save the Charles.ini file.

Each user will need to configure Charles to use a different port. I suggest setting Charles to use a dynamic port.

If you need to run multiple instances of Charles as the same user you need to use a command-line option to direct Charles to use a different config file.

Permalink

How does Charles calculate latency?

Charles shows a measure of the latency on each request on the Overview tab. Charles calculates latency by measuring the time taken between finishing sending the request and starting to receive the response. Therefore latency includes network latency and server latency, that is the time spent processing the request.

For static requests the server is usually able to respond instantly, unless under load, so the latency figure mostly represents the network latency.

For dynamic requests, or any request for which the server has to do some work, you can subtract an approximate network latency to determine how long the server spent processing the request.

Permalink

What's with the logo?

The jug is part of the Charles folklore. It once belonged to a man named Charles, but Charles is not named after him.

Permalink

Accessing .local domains is slow on Mac OS X

This appears to be a fault in Mac OS X Lion, where it takes 5 seconds to resolve .local domain names, even if they are hardcoded in your /etc/hosts file. You can work around this problem by using Charles's DNS Spoofing tool intead of /etc/hosts, however you'll experience the .local DNS resolution delay when not using Charles. I recommend using an alternative TLD such as .dev.

More information

Permalink

SSL

SSL decryption no longer works after Charles 3.4 upgrade

Charles 3.4 changes the default behaviour of SSL in Charles to opt-in rather than opt-out. You must now opt-in each site you wish to enable for SSL proxying. This change was made to improve the behaviour of Charles. There are a number of applications running on computers that require SSL connections and get confused by the Charles SSL certificate used for SSL proxying. Also defaulting every site into SSL proxying could cause unwitting security problems for Charles users, such as if you Internet Banking site is proxied and your password visible in plain text inside Charles.

This change does mean that you now need to tell Charles about each SSL site you want to proxy, or you can opt in to proxy them all again.

To opt in a specific site, right-click on the host name in the tree view and turn on SSL Proxying. You may need to restart your browser to get it to close its existing non-SSL proxied connection. You can also control the list of SSL proxied hosts in the Proxy Settings dialog.

To opt in all sites, open the Proxy Settings dialog, go to the SSL tab, and enter a * into the list of locations.

Permalink

SSL certificate warnings appear in my browser or other client

These warnings will appear if you're using Charles's SSL Proxying feature. You can configure your browser (or other client application) to trust the SSL certificates that Charles generates, or you can just trust individual certificates (if the browser or application gives you that option).

Permalink

Licensing

Lost my license key

No problem! Please use the Lost License Key form to automatically receive a new email containing your key. If you still can't recover your key please contact me using the Contact Form and place a Sales enquiry.

Permalink

Deploying license keys during installation

In order to deploy license keys during installation you need to copy a Charles preferences file into the appropriate location. Please configure a copy of Charles with the correct license key and then make a copy of the preferences file to use as the source file.

Please ensure that you have sufficient Charles licenses for your installation.

The Charles preferences file is found in different locations on each OS:

  • Windows: %APPDATA%\Charles\charles.config
  • Mac OS X: ~/Library/Preferences/com.xk72.charles.config
  • Linux: ~/.charles.config

Permalink

iPhone

Using Charles from an iPhone

To use Charles as your HTTP proxy on your iPhone you must manually configure the HTTP Proxy settings on your WiFi network in your iPhone's Settings.

Go to the Settings app, tap Wi-Fi, find the network you are connected to and then tap the blue disclosure arrow to configure the network. Scroll down to the HTTP Proxy setting, tap Manual. Enter the IP address of your computer running Charles in the Server field, and the port Charles is running on in the Port field (usually 8888). Leave Authentication set to Off.

All of your web traffic from your iPhone will now be sent via Charles. You should see a prompt in Charles when you first make a connection from the iPhone, asking you to allow the traffic.

Remember to disable the HTTP Proxy in your Settings when you stop using Charles, otherwise you'll get confusing network failures in your applications!

Permalink

SSL connections from within iPhone applications

Simulator

Download this configuration shell script, unzip and then double-click it on your Mac. This will backup and then add Charles's SSL CA certificate to the keychain for your iPhone and iPad simulator. You don't even have to restart the simulator for it to take effect, usually.

Alternatively, you can change your code so that NSURLConnection accepts any SSL certificate. Please see the question and answer on Stack Overflow: http://stackoverflow.com/questions/933331/how-to-use-nsurlconnection-to-connect-with-ssl-for-an-untrusted-cert

If you're only browsing a single website in Safari you can just accept the certificate in Safari and that will work for a while. If the SSL site is only being used to load resources such as images, then you'll need to visit it directly and accept the certificate before it will work.

Device

iOS 4 and later

On the device, browse to http://charlesproxy.com/charles.crt then install the certificate.

iOS 3

On the device you need to install a Charles Proxy mobile configuration profile. This profile contains the Charles SSL CA certificate so that your device will then trust the SSL certificates that Charles creates, in the same way as the desktop does. In Safari on your device visit http://charlesproxy.com/iphoneconf which will download the mobile configuration profile and prompt you to install.

Permalink

Troubleshooting

Outlook for Mac can't check email

Outlook for Mac doesn't play nicely with Charles. Add the hostname of your mail server to the Bypass Proxies text area in the Proxy Settings, Options tab. For example, "mail.example.com". This will configure your system to not use Charles as its proxy when connecting to your mail server.

Permalink