lingochamp/FileDownloader · error · SocketException

Connection failed with request

Error message

Connection failed with request[%s] response[%s] http-state[%d] on task[%d-%d], which is changed after verify connection, so please try again.

What it means

A SocketException thrown in DownloadRunnable.run when a per-connection response code is neither HTTP 206 Partial Content nor HTTP 200 OK during a multi-connection download. The message indicates the server's response changed after the trial/verify connection succeeded — i.e., the connection that previously validated now returns an unexpected status. The task should simply be retried.

Solutions

1. Simply retry the download — the message explicitly says 'please try again' (FileDownloader handles retries; ensure retryCount is set appropriately)
2. Catch SocketException in the FileDownloadListener error callback and restart the task
3. Verify the URL/token lifetime is long enough that signed URLs do not expire mid-download
4. Test server consistency: confirm the URL reliably returns 200/206 and supports Range (curl -H 'Range: bytes=0-99' -I)
5. Pin to a different/more stable CDN endpoint or mirror URL

Example fix

// before: single-attempt listener
FileDownloader.getImpl().create(url).setPath(path).start(listener);
// after: let the library retry and handle residual errors
FileDownloader.getImpl().create(url)
    .setPath(path)
    .setRetryCount(3)
    .start(new FileDownloadListener() {
        @Override public void error(FileDownloadTask task, Throwable e) {
            if (e instanceof SocketException) {
                // retry manually with backoff or switch to fallback URL
            }
        }
    });

HttpURLConnection c = (HttpURLConnection) new URL(url).openConnection();
c.setRequest("Range", "bytes=0-99");
int code = c.getResponseCode();
if (code != 206 && code != 200) throw new IllegalStateException("Server unstable for range downloads, code=" + code);

try {
    FileDownloader.getImpl().create(url).setPath(path).setRetryCount(3).start(listener);
} catch (SocketException e) {
    // server changed response between verify and download; retry with backoff or switch URL
    retryWithBackoffOrFallbackUrl();
}

When it happens

Trigger: During multi-connection downloads, any connection receiving a code other than 200/206 after the initial verify connection returned a valid code — e.g. server began returning 403/404/5xx, rate-limited, or dropped Range support between the verify request and the actual range requests.

Common situations: Flaky CDNs or load balancers with inconsistent behavior across nodes; signed URLs expiring between verify and download; servers that intermittently reject Range requests; unstable networks causing server-side session loss; heavy server load returning 5xx.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• response code error: , request headers: response headers
• the download runnable must not be null!
• The file is too large to store, breakpoint in bytes
• Task[ ] can't start the download runnable, because this…
• fetched length[ ] != content length[ ], range[ , ) offset[…

AI-assisted analysis of lingochamp/FileDownloader@6237a8cac1 (2026-09-08). Data as JSON: /api/errors/aa83b281f789fd34. Report an issue: GitHub.

Appendix: source

Thrown at library/src/main/java/com/liulishuo/filedownloader/download/DownloadRunnable.java:96

        do {

            try {
                if (paused) {
                    return;
                }

                isConnected = false;
                connection = connectTask.connect();
                final int code = connection.getResponseCode();

                if (FileDownloadLog.NEED_LOG) {
                    FileDownloadLog
                            .d(this, "the connection[%d] for %d, is connected %s with code[%d]",
                                    connectionIndex, downloadId, connectTask.getProfile(), code);
                }

                if (code != HttpURLConnection.HTTP_PARTIAL && code != HttpURLConnection.HTTP_OK) {
                    throw new SocketException(FileDownloadUtils.
                            formatString(
                                    "Connection failed with request[%s] response[%s] "
                                            + "http-state[%d] on task[%d-%d], which is changed"
                                            + " after verify connection, so please try again.",
                                    connectTask.getRequestHeader(),
                                    connection.getResponseHeaderFields(),
                                    code, downloadId, connectionIndex));
                }

                isConnected = true;
                final FetchDataTask.Builder builder = new FetchDataTask.Builder();

                if (paused) return;
                fetchDataTask = builder
                        .setDownloadId(downloadId)
                        .setConnectionIndex(connectionIndex)
                        .setCallback(callback)
                        .setHost(this)

View on GitHub (pinned to 6237a8cac1)