The Chromium Projects

Search this site

Except as otherwise noted, the content of this page is licensed under a Creative Commons Attribution 2.5 license, and examples are licensed under the BSD License.
For Developers‎ > ‎Design Documents‎ > ‎Network Stack‎ > ‎

Debugging problems with the network proxy

When browsers are experiencing network problems, generally the first thing to test is your network proxy settings.
Misconfigured settings, or misbehaving settings, can have a profound impact on your network traffic (possibly resulting in pages not loading at all).

Main take aways:
  • chrome://net-internals/proxy-service
  • Enable logging and look for proxy warnings / errors
Note: this document talks about some features which are not present in versions of chrome prior to 4.

What proxy settings does Chrome use?

By default, Chrome will use your "system proxy settings".
Exactly what this means varies across platforms.

What are the "system proxy settings"?

Windows

On Windows, Chrome uses the WinInet proxy configuration.
These are the same settings that Internet Explorer uses.

Mac OS X

On Mac, Chrome uses the proxy settings listed under the Network Control Panel.
These are the same settings that Safari uses.

Linux

On Linux, Chrome uses either GNOME / KDE proxy settings, or will use certain environment variables.

Testing the system proxy settings

It is important to note that certain browsers like Firefox use a different set of proxy settings.
So when something fails to load in Firefox but works in Chrome, it could well be that they are using different configurations, and that for Chrome is wrong.

To test this theory, it is easiest to load a webpage in another browser that we know to be using the same proxy settings as Chrome.
If it fails in the same way for that other browser, it is a good bet that the "system proxy settings" are wrong and need to be changed.

Windows

On Windows we can try loading a webpage in Internet Explorer and see if it fails in the same way.

Mac OS X

On Mac we can try loading a webpage in Safari and see if it fails in the same way.

What proxy settings is Chrome actually using?

The best way to see what proxy settings chrome is really using, is to navigate to this special page in Chrome:

    chrome://net-internals/proxyservice.config

This will dump out something resembling:

Automatic settings:
  Auto-detect: Yes
  Custom PAC script: http://foobar/my_pac_script.js
Manual settings:
  Proxy server: [None]
  Bypass list: [None]
  Bypass local names: No

Which enumerates the precise settings that Chrome is using.

By default, chrome will have fetched these settings from the "system proxy settings".

When investigating misconfiguration problems, the first thing to check is whether these settings are intended (the values could have been overrided by flags),
and whether Chrome actually fetched the correct settings from the system.

NOTE: The proxy settings are fetched lazily on a 10 second poll delay, during HTTP requests.
If the proxyservice.config page says it is not yet initialized, or is otherwise stale, try loading some other webpage and then refreshing.

How are the proxy settings applied?

It is possible to specify multiple competing proxy settings (for example, on Windows you could enable the auto-detect option, AND specify a manual proxy server).

In such cases, chrome will use the following proxy settings fallback sequence, which matches Internet Explorer.
This fallback sequence is used on other platforms too, but since there generally isn't a way to specify such configurations it doesn't come up.

Specifically, you can check the sequence of steps that Chrome ran through to apply the proxy settings by navigating to this URL:

chrome://net-internals/proxyservice.init_log

How do I debug a PAC script? Why can't I see the alert() and javascript errors it gave?

Any errors or log messages generated by PAC script evaluation, are sent to the chrome_debug.log file.
To see them, you must enable logging.

I don't want to use the system proxy settings... how do I override them?

You will have to use command-line flags to override.
These are the ones available:

--no-proxy-server
--proxy-auto-detect
--proxy-bypass-list=XXX
--proxy-pac-url=XXX
--proxy-server=XXX

See the source code for documentation.

For example:

Send all traffic through the SOCKS 5 server "foobar:1080"
    chrome --proxy-server="socks5://foobar:1080"

Send all traffic through the HTTP proxy server "foo:6233"
    chrome --proxy-server="foo:6233"

Use the custom PAC script to resolve proxy servers:
    chrome --proxy-pac-url="file:///home/foobar/tmp/myscript.js"

It works fine in Internet Explorer, but fails in Chrome

As an experiment you can try running Chrome with the command-line flag

--winhttp-proxy-resolver

This will select an alternate implementation of proxy resolving that uses the WinHTTP library (only available on Windows).

Make note of whether this works.

We aim to be fully compatible with Internet Explorer's proxy settings, so if you run into an incompatibility please file a bug (and cc eroman@chromium.org)
The only known caveat right now is we don't support all of the Microsoft PAC extensions. The unimplemented functions are:

isInNetEx()
sortIpAddressesList()

You can monitor the status in bug 25407.

Browsing is slow... it keeps saying "Resolving proxy..."

One common cause of this is PAC scripts which make use of DNS resolves within the PAC script (DNS resolving can be arbitrarily slow, especially for host names that don't exist).

The first step to debugging this, is to load up:

chrome://net-internals/

And search for the URL you were trying to load.

In particular, you will get to see a finer-granularity breakdown of where the time was spent in the proxy resolving stage.
This stage can be quite complex, and might involve any or all of the following:

  • Fetching the system proxy settings.
  • Downloading the WPAD auto-configuration script.
  • Downloading the custom PAC script.
  • Executing the javascript of a PAC script.
  • Doing DNS resolves within the PAC script.

Comments