arduino/Arduino · error · IllegalStateException

Unable to understand proxy settings

Error message

Unable to understand proxy settings

What it means

CustomProxySelector.getProxyFor() dispatches on the configured proxy type (auto/PAC, manual, none via earlier branches). If Constants.PREF_PROXY_TYPE holds a value matching none of the known branches, it falls through and throws an IllegalStateException, indicating the proxy settings in preferences are unrecognizable.

Source

Thrown at arduino-core/src/cc/arduino/net/CustomProxySelector.java:74

    if (Constants.PROXY_TYPE_NONE.equals(proxyType)) {
      return Proxy.NO_PROXY;
    }

    if (Constants.PROXY_TYPE_AUTO.equals(proxyType)) {
      String pac = preferences.get(Constants.PREF_PROXY_PAC_URL);
      if (pac == null || pac.isEmpty()) {
        return ProxySelector.getDefault().select(uri).get(0);
      }

      return pacProxy(pac, uri);
    }

    if (Constants.PROXY_TYPE_MANUAL.equals(proxyType)) {
      return manualProxy();
    }

    throw new IllegalStateException("Unable to understand proxy settings");
  }

  private Proxy pacProxy(String pac, URI uri) throws IOException, ScriptException, NoSuchMethodException {
    setAuthenticator(preferences.get(Constants.PREF_PROXY_USERNAME), preferences.get(Constants.PREF_PROXY_PASSWORD));

    URLConnection urlConnection = new URL(pac).openConnection();
    urlConnection.connect();
    if (urlConnection instanceof HttpURLConnection) {
      int responseCode = ((HttpURLConnection) urlConnection).getResponseCode();
      if (responseCode != 200) {
        throw new IOException("Unable to fetch PAC file at " + pac + ". Response code is " + responseCode);
      }
    }
    String pacScript = new String(IOUtils.toByteArray(urlConnection.getInputStream()), Charset.forName("ASCII"));

    ScriptEngine nashorn = new ScriptEngineManager().getEngineByName("nashorn");
    nashorn.getBindings(ScriptContext.ENGINE_SCOPE).put("pac", new PACSupportMethods());
    Stream.of("isPlainHostName(host)",

View on GitHub (pinned to a0df6e0e83)

Solutions

1. Set the proxy type preference to a supported value (none/auto/manual) in preferences.txt or File > Preferences.
2. Delete the invalid proxy type preference entry so defaults are used, then reconfigure the proxy.
3. Check for case/whitespace errors in the stored value and match exactly what Constants.PREF_PROXY_TYPE expects.
4. If an external tool sets this preference, fix its writer to emit only recognized enum values.

Example fix

// before (preferences.txt)
proxy.type=SOCKS5
// after
proxy.type=MANUAL

String type = preferences.get(Constants.PREF_PROXY_TYPE);
Set<String> valid = Set.of(Constants.PROXY_TYPE_NONE, Constants.PROXY_TYPE_AUTO, Constants.PROXY_TYPE_MANUAL);
if (type != null && !valid.contains(type)) { throw new IllegalStateException("Unsupported proxy type: " + type); }

try { Proxy p = new CustomProxySelector(prefs).getProxyFor(uri); } catch (IllegalStateException e) { if (e.getMessage().contains("Unable to understand proxy settings")) { resetProxyPreferences(); } else { throw e; } }

When it happens

Trigger: getProxyFor() (called from proxy()) reads Constants.PREF_PROXY_TYPE and the value is not PROXY_TYPE_AUTO/PAC, not PROXY_TYPE_MANUAL, and not the none/system alternatives handled earlier — e.g. a typo'd or foreign value in preferences.txt.

Common situations: Hand-edited preferences.txt with an invalid proxy type string; a downgrade/upgrade where preference key values changed between IDE versions; provisioning tools writing 'PAC'/'socks' or other unsupported values.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Board is not selected
• CRC doesn't match, file is corrupted. It may be a temporary
• Error downloading {0}
• Unable to fetch PAC file at {pac}. Response code is {respons
• Unable to find a way to connect

AI-assisted analysis of arduino/Arduino@a0df6e0e83 (2026-09-06). Data as JSON: /api/errors/760e2d3ccf7a02dc. Report an issue: GitHub.