alibaba/spring-ai-alibaba · error · WebFetchException

Network error while fetching URL:

Error message

Network error while fetching URL: 

What it means

fetchHtml (the single-attempt HTTP call in WebFetchTool) wraps IOException from the JDK HttpClient into WebFetchException with 'Network error while fetching URL: <message>'. This is the per-attempt failure that retry logic counts; the message carries the underlying IOException text.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/tools/WebFetchTool.java:342

				@Override
				public Optional<javax.net.ssl.SSLSession> sslSession() {
					return byteResponse.sslSession();
				}

				@Override
				public URI uri() {
					return byteResponse.uri();
				}

				@Override
				public java.net.http.HttpClient.Version version() {
					return byteResponse.version();
				}
			};
		}
		catch (IOException e) {
			throw new WebFetchException("Network error while fetching URL: " + e.getMessage(), e);
		}
		catch (InterruptedException e) {
			Thread.currentThread().interrupt();
			throw new WebFetchException("Request was interrupted", e);
		}
	}

	private Optional<Charset> extractCharset(HttpResponse<?> response) {
		return response.headers()
			.firstValue("Content-Type")
			.flatMap(contentType -> {
				Matcher matcher = CHARSET_PATTERN.matcher(contentType);
				if (matcher.find()) {
					String charsetName = matcher.group(1);
					try {
						return Optional.of(Charset.forName(charsetName));
					}
					catch (Exception e) {

View on GitHub (pinned to f82da0b50f)

Solutions

1. Read the appended IOException message to identify the exact network failure.
2. Test the URL from the same host/network with curl.
3. Configure proxies and DNS for the runtime environment.
4. Rely on fetchHtmlWithRetry or wrap the call in your own retry with backoff for transient errors.

Example fix

// before
catch (WebFetchException e) { throw e; }
// after
catch (WebFetchException e) {
    // e.getMessage() contains the underlying IOException message
    return fallbackSummaryFor(url, e);
}

InetAddress.getByName(URI.create(url).getHost()); // fails fast if DNS cannot resolve

try {
    String html = webFetchTool.fetch(url);
} catch (WebFetchException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Network error")) {
        return retryWithBackoff(url); // transient IOException
    }
    throw e;
}

When it happens

Trigger: HttpClient.send throws IOException — connection refused/reset, unknown host, TLS handshake failure, socket timeout, or reading the response body fails.

Common situations: Target site blocks the agent's user agent; DNS not resolvable inside a container; server closes keep-alive connections; SSL certificates not trusted in the JVM.

Related errors

• Oauth2CallError
• Failed after attempts
• Failed after attempts:
• Fetch attempt {} failed for URL: {}: {}
• Failed to subscribe

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/5b68092a11ce86cd. Report an issue: GitHub.