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

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 the settings are 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/#proxy

This will dump out something resembling:

Effective proxy settings

Use DIRECT connections.

Original proxy settings

PAC script: http://my-custom-pac/wpad.dat
Source: SYSTEM

Which enumerates the settings that Chrome is using.

Note that the configured settings "Original proxy settings" may be different from the effective settings (how they are interpreted). This is due to fallbacks which can happen on failure, or proxy discovery.

When investigating misconfiguration problems, the first thing to check is whether these settings are intended (the values could have been overriden by flags, extensions, or even other software on the system, and whether Chrome actually fetched the correct settings from the system.

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 looking at

chrome://net-internals/#events

And filtering for "PROXY_SCRIPT_DECIDER".

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 NetLog. To see them look in chrome://net-internals/#events

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

There are several mechanisms for overriding proxy settings in Chrome:

  1. Managed settings
  2. Chrome extensions
  3. Command line flags:
--no-proxy-server
--proxy-auto-detect
--proxy-bypass-list=XXX
--proxy-pac-url=XXX
--proxy-server=XXX

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. (This flag also works in Mac OS versions of Chrome, however the meaning of the flag is different. Really just means "use system library").

Make note of whether this works.

We aim to be compatible with Internet Explorer's proxy settings, so if you run into an incompatibility please file a bug. There are some known issues with Chrome using WinHTTP to retrieve Internet Explorer's proxy settings, rather than using WinInet (bug 118385)

Comments