FAQs
General
Localhost traffic doesn't appear in Charles
Some systems are hard coded to not use proxies for localhost traffic, so when you connect to http://localhost/ it doesn't show up in Charles.
The workaround is to connect to http://localhost.charlesproxy.com/ instead. This points to the IP address 127.0.0.1, so it should work identically to localhost, but with the advantage that it will go through Charles. This will work whether or not Charles is running or you're using Charles. If you use a different port, such as 8080, just add that as you usually would, e.g. localhost.charlesproxy.com:8080.
You can also put anything in front of that domain, e.g. myapp.localhost.charlesproxy.com, which will also always resolve to 127.0.0.1.
Alternatively you can try adding a '.' after localhost, or replace localhost with the name of your machine, or use your local link IP address (eg. 192.168.1.2).
If Charles is running and you're using Charles as your proxy, you can also use local.charles as an alternative for localhost. Note that this only works when you're using Charles as your proxy, so the above approaches are preferred, unless you specifically want requests to fail if not using Charles.
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.
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.
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.
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 described 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 Files\Charles), 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.
Can't authenticate through NTLM / Windows Integrated 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
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/).
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.
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!
Try starting Charles before establishing the VPN connection. If you quit and relaunch Charles while the VPN is running, you may need to disconnect and reconnect the VPN again.
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.
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.
The jug is part of the Charles folklore. It once belonged to a man named Charles, but Charles is not named after him.
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.
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.
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).
Localhost SSL traffic fails with ERR_CONNECTION_CLOSED in Chrome
Chrome by default rejects all localhost traffic if it has an invalid SSL certificate. This invalid certificate may be due to not trusting the Charles SSL certificate, or it may be because the SSL certificate your localhost server is using has expired or has the wrong name.
Check the connection, and your certificate, in another browser, as other browsers are not so stringent.
If this is the issue, we recommend fixing the issue with your certificate—such as renewing it or adding the correct common name to the certificate.
You can also change the setting in Chrome, so it no longer rejects these certificates outright. Do this by going to chrome://flags/#allow-insecure-localhost and enabling Allow invalid certificates for resources loaded from localhost.
Licensing
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.
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
iOS
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!
SSL connections from within iPhone applications
Simulator
As of Charles v3.9.3 there is an item in the Help menu, "Install Charles CA SSL Certificate in iOS Simulators", which will automatically install Charles's SSL CA certificate in your iOS Simulators.
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 that site. 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, set your HTTP proxy to use Charles, and then browse to http://www.charlesproxy.com/getssl to install the certificate.
SSL Pinning
Note that some apps implement SSL certificate pinning which means they specifically validate the root certificate. Because the app is itself verifying the root certificate it will not accept Charles's certificate and will fail the connection. If you have successfully installed the Charles root SSL certificate and can browse SSL websites using SSL Proxying in Safari, but an app fails, then SSL Pinning is probably the issue.
After you've installed the root SSL certificate for your installation of Charles on your iOS device, you will be able to use SSL Proxying with apps. As of Charles 3.11.4 you can now do this with apps compiled and running on iOS 9 with App Transport Security.
Note that some apps implement SSL certificate pinning which means they specifically validate the root certificate, and will not work with Charles.
If you are on iOS 10.3 or later, there is an extra step required to trust Charles's root SSL certificate. Open the Settings.app and navigate to General > About > Certificate Trust Settings, and find the Charles Proxy certificate, and switch it on to enable full trust for it (More information about this change in iOS 10).
In the event that you continue to have difficulties using SSL Proxying with your own apps, you could try disabling ATS. To disable ATS you need to add keys to your app's Info.plist file, as below. See this tech note from Apple for more information.
You must remember to re-enable ATS before you release your app to take advantage of the security that ATS provides.
<key>NSAppTransportSecurity</key> <dict> <key>NSAllowsArbitraryLoads</key> <true/> </dict>
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.