spring-projects/spring-ai · error · RuntimeException

Failed to read HTML resource

Error message

Failed to read HTML resource: <htmlResource>

What it means

Wraps an IOException raised while fetching or reading the HTML resource in JsoupDocumentReader.get: the URL/connection could not be opened or read, so document extraction is aborted with a RuntimeException carrying the resource name.

Solutions

1. Verify the HTML resource URL is correct and reachable
2. Check network/proxy/firewall settings
3. Pre-download the resource locally and pass a file/classpath resource

When it happens

Trigger: Thrown at document-readers/spring-ai-jsoup-document-reader/src/main/java/org/springframework/ai/reader/jsoup/JsoupDocumentReader.java:107 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/9401bd73465b0b05. Report an issue: GitHub.

Appendix: source

Thrown at document-readers/spring-ai-jsoup-document-reader/src/main/java/org/springframework/ai/reader/jsoup/JsoupDocumentReader.java:107

					addMetadata(doc, document);
					// Do not add metadata from element to avoid duplication.
					documents.add(document);
				}
			}
			else {
				// Extract text from specific elements based on the selector
				Elements elements = doc.select(this.config.selector);
				String text = elements.stream().map(Element::text).collect(Collectors.joining(this.config.separator));
				Document document = new Document(text);
				addMetadata(doc, document);
				documents.add(document);
			}

			return documents;

		}
		catch (IOException e) {
			throw new RuntimeException("Failed to read HTML resource: " + this.htmlResource, e);
		}
	}

	private void addMetadata(org.jsoup.nodes.Document jsoupDoc, Document springDoc) {
		Map<String, Object> metadata = new HashMap<>();
		metadata.put("title", jsoupDoc.title());

		for (String metaTag : this.config.metadataTags) {
			String value = jsoupDoc.select("meta[name=" + metaTag + "]").attr("content");
			if (!value.isEmpty()) {
				metadata.put(metaTag, value);
			}
		}

		if (this.config.includeLinkUrls) {
			Elements links = jsoupDoc.select("a[href]");
			List<String> linkUrls = links.stream().map(link -> link.attr("abs:href")).toList();
			metadata.put("linkUrls", linkUrls);

View on GitHub (pinned to 98a7beda4f)