arduino/Arduino · error · IOException

Received invalid http status code from server

Error message

Received invalid http status code from server: {resp}

What it means

FileDownloader throws this IOException when the HTTP response code of the download request falls outside the 200-299 range. The partial output file is deleted first so no corrupt download remains, then the error names the exact status code received.

Solutions

1. Verify the download URL is correct and reachable (open it in a browser or curl -I)
2. Check proxy settings in Arduino preferences if behind a corporate proxy
3. Retry after a delay for transient 5xx responses
4. Check authentication/firewall rules if the server returns 403

Example fix

// before: no pre-check
downloader.downloadFile(new URL(url), file, false);
// after: HEAD-check and retry
HttpURLConnection c = (HttpURLConnection) new URL(url).openConnection();
c.setRequestMethod("HEAD");
if (c.getResponseCode() < 200 || c.getResponseCode() >= 300) throw new IOException("URL unavailable: " + c.getResponseCode());
downloader.downloadFile(new URL(url), file, false);

HttpURLConnection c = (HttpURLConnection) url.openConnection();
c.setRequestMethod("HEAD");
if (c.getResponseCode() < 200 || c.getResponseCode() >= 300)
  throw new IllegalStateException("URL not downloadable: " + c.getResponseCode());

try {
  downloader.downloadFile(url, file, false);
} catch (IOException e) {
  if (e.getMessage().contains("Received invalid http status code")) {
    // check proxy settings / retry with backoff
    configureProxy();
    downloader.downloadFile(url, file, false);
  } else throw e;
}

When it happens

Trigger: downloadFile() calls openConnectionAndFillTheFile(), which calls HttpConnectionManager.makeConnection(); connection.getResponseCode() returns < 200 or >= 300 (e.g. 403 Forbidden, 404 Not Found, 500, or a non-handled 3xx).

Common situations: Download URL points to a moved/removed resource (404); server or CDN blocks the client (403); proxy misconfiguration (CustomProxySelector) returning an error page; transient 5xx during heavy load.

Related errors

• Error downloading
• CRC doesn't match, file is corrupted. It may be a temporary…
• Exceeded redirects.
• Incomplete download
• Received response with content-encoding

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

Appendix: source

Thrown at arduino-core/src/cc/arduino/utils/network/FileDownloader.java:222

    }
    return Optional.empty();
  }

  private void openConnectionAndFillTheFile(boolean noResume) throws Exception {
    initialSize = outputFile.length();
    if (noResume && initialSize > 0) {
      // delete file and restart downloading
      Files.deleteIfExists(outputFile.toPath());
      initialSize = 0;
    }

    final HttpURLConnection connection = new HttpConnectionManager(downloadUrl)
      .makeConnection((c) -> setDownloaded(0));
    final int resp = connection.getResponseCode();

    if (resp < 200 || resp >= 300) {
      Files.deleteIfExists(outputFile.toPath());
      throw new IOException("Received invalid http status code from server: " + resp);
    }

    RandomAccessFile randomAccessOutputFile = null;
    try {
      // Open file and seek to the end of it
      randomAccessOutputFile = new RandomAccessFile(outputFile, "rw");
      randomAccessOutputFile.seek(initialSize);
      readStreamCopyTo(randomAccessOutputFile, connection);
    } finally {
      IOUtils.closeQuietly(randomAccessOutputFile);
    }

  }

  private void readStreamCopyTo(RandomAccessFile randomAccessOutputFile, HttpURLConnection connection) throws Exception {
    InputStream stream = null;
    try {
      // Check for valid content length.

View on GitHub (pinned to a0df6e0e83)