The SPARQL endpoint refuses a query result longer than it can answer with

A CONSTRUCT on the Northwind demo's root document matched the whole dataset:
its { BIND(?resource AS ?s) ?s ?p ?o } branch sees ?resource unbound, so it
returned 83,251 triples (13.8 MB as N-Triples) where 182 were meant. Nothing
bounded the result on its way: the endpoint buffered and hashed all of it,
and Saxon-JS held the page's thread for ~30 s tabling it. The SPARQL client
is exempt from MAX_CONTENT_LENGTH since b7261d9, rightly - that limit
bounds untrusted input, and the platform's own lookups must read its store
whatever its size.

What bounds a query result is what its consumer can take, so it is a limit
of its own, MAX_QUERY_RESPONSE_LENGTH (5 MiB unless set), applied only to
HTTP callers of /sparql: SPARQLEndpointImpl takes a capped accessor from
ServiceContext.getQueryEndpointAccessor(), and Access and the Graph Store
keep the uncapped one. ContentLengthLimitFilter honours a per-request
MAX_CONTENT_LENGTH property, which ResponseLengthLimitFilter sets and
enforces, so the query limit replaces the client-wide one rather than
stacking under it. The stream is cut where it passes the limit, so the
result is never buffered whole. A refusal, not truncation: a caller that
needs more pages with LIMIT/OFFSET.

The refusal stays 502, as the proxy's does, and its description is typed
ldh:ResponseTooLarge, so the client can tell it from an upstream that could
not be reached: ldh:http-error-key($response) reads the type, and every
call site holding the response uses it ("The result is larger than this
server returns. Narrow the query or add a LIMIT."). The SSR error card in
document.xsl reads the same type.

Verified: unit test for the per-request limit (ContentLengthLimitFilterTest
9/9); a scratch probe through Jersey + Jena against a chunked server - an
oversized CONSTRUCT and SELECT raise ResponseContentTooLargeException
unwrapped, and a 2.5 MB result passes a 3 MB query limit under a 2 MB
client-wide one; make sef; the SSR stylesheet compiles.

NOT yet verified end to end: the image has not been rebuilt, so the new
HTTP test (POST-sparql-response-too-large-502.sh) and the query block UI
spec case have not run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: namedgraph

.env_sample

@@ -17,6 +17,9 @@ OWNER_STATE_OR_PROVINCE=Denmark
 OWNER_COUNTRY_NAME=DK
 
 MAX_CONTENT_LENGTH=2097152
+# the longest result, in bytes, the /sparql endpoint answers a query with; a longer one is refused with 502. Counted on the
+# store's response to the platform, not on what the caller receives. 5242880 (5 MiB) when unset
+# MAX_QUERY_RESPONSE_LENGTH=5242880
 
 # the assistant is opt-in: its plan service (the web-algebra container) is a proprietary image, distributed without its
 # source. Uncomment to run it and offer it in the UI

AGENTS.md

@@ -138,6 +138,7 @@ A single instance hosts multiple **dataspaces**, each a subdomain (origin). Each
 - **`403` where you expect `404`.** The ACL query fails closed on a typeless resource, so a non-owner request for a URL that does not exist is answered `403`.
 - **`428`** on any write to an existing document that carries no `If-Match`; **`412`** when the tag quoted was read under a different negotiated variant. See *Conditional writes*.
 - **`502`** (rather than `413`) when an upstream response exceeds `MAX_CONTENT_LENGTH`: what was too large is the upstream's response. Requests to the deployment's own SPARQL, Graph Store and Quad Store services are exempt from the bound.
+- **`502`** from `/sparql` when the query's result exceeds `MAX_QUERY_RESPONSE_LENGTH` (5 MiB unless set), its body typed `ldh:ResponseTooLarge`. The result is refused, not truncated: page through it with `LIMIT`/`OFFSET`.
 - **`406`** for `application/link-format` on anything but `?timemap`.
 
 ## Tooling

README.md

@@ -246,6 +246,8 @@ _:warning: Do not use blank nodes to identify applications or services. We recom
     <dd>The period for which the data import can keep an open HTTP connection before it times out, in ms. The larger files are being imported, the longer it has to be in order for the import to complete.</dd>
     <dt><code>MAX_CONTENT_LENGTH</code></dt>
     <dd>Maximum allowed size of the request body, in bytes</dd>
+    <dt><code>MAX_QUERY_RESPONSE_LENGTH</code></dt>
+    <dd>Maximum length of a query result the <code>/sparql</code> endpoint answers with, in bytes. A longer one is refused with <code>502</code>. 5242880 (5 MiB) by default</dd>
     <dt><code>COMPOSE_PROFILES</code></dt>
     <dd><code>assistant</code> to run and offer the <a href="#assistant">assistant</a>. Disabled by default</dd>
     <dt><code>MAIL_SMTP_HOST</code></dt>

docker-compose.yml

@@ -66,6 +66,7 @@ services:
       - SELF_SIGNED_CERT=true # only on localhost
       - SIGN_UP_CERT_VALIDITY=180
       - MAX_CONTENT_LENGTH=${MAX_CONTENT_LENGTH:-2097152}
+      - MAX_QUERY_RESPONSE_LENGTH=${MAX_QUERY_RESPONSE_LENGTH:-} # 5 MiB unless set (Application.DEFAULT_MAX_QUERY_RESPONSE_LENGTH)
       - ALLOW_INTERNAL_URLS=${ALLOW_INTERNAL_URLS:-}
       - ENABLE_SITEMAP=${ENABLE_SITEMAP:-} # opt-in: /sitemap.xml queries every public document of the dataspace
       - COMPOSE_PROFILES=${COMPOSE_PROFILES:-} # the "assistant" profile also makes the UI offer the assistant (entrypoint.sh)

platform/context.xsl

@@ -37,6 +37,7 @@ xmlns:orcid="&orcid;"
     <xsl:param name="ldhc:ownerAuthQuery"/>
     <xsl:param name="ldhc:enableLinkedDataProxy"/>
     <xsl:param name="ldhc:maxContentLength"/>
+    <xsl:param name="ldhc:maxQueryResponseLength"/>
     <xsl:param name="ldhc:maxImportThreads"/>
     <xsl:param name="ldhc:notificationAddress"/>
     <xsl:param name="ldhc:enableWebIDSignUp"/>
@@ -125,6 +126,9 @@ xmlns:orcid="&orcid;"
             <xsl:if test="$ldhc:maxContentLength">
                 <Parameter name="&ldhc;maxContentLength" value="{$ldhc:maxContentLength}" override="false"/>
             </xsl:if>
+            <xsl:if test="$ldhc:maxQueryResponseLength">
+                <Parameter name="&ldhc;maxQueryResponseLength" value="{$ldhc:maxQueryResponseLength}" override="false"/>
+            </xsl:if>
             <xsl:if test="$ldhc:maxImportThreads">
                 <Parameter name="&ldhc;maxImportThreads" value="{$ldhc:maxImportThreads}" override="false"/>
             </xsl:if>

platform/entrypoint.sh

@@ -1149,6 +1149,10 @@ if [ -n "$MAX_CONTENT_LENGTH" ]; then
     MAX_CONTENT_LENGTH_PARAM="--stringparam ldhc:maxContentLength '$MAX_CONTENT_LENGTH' "
 fi
 
+if [ -n "$MAX_QUERY_RESPONSE_LENGTH" ]; then
+    MAX_QUERY_RESPONSE_LENGTH_PARAM="--stringparam ldhc:maxQueryResponseLength '$MAX_QUERY_RESPONSE_LENGTH' "
+fi
+
 if [ -n "$MAX_IMPORT_THREADS" ]; then
     MAX_IMPORT_THREADS_PARAM="--stringparam ldhc:maxImportThreads '$MAX_IMPORT_THREADS' "
 fi
@@ -1228,6 +1232,7 @@ transform="xsltproc \
   $OWNER_AUTH_QUERY_PARAM \
   $ENABLE_LINKED_DATA_PROXY_PARAM \
   $MAX_CONTENT_LENGTH_PARAM \
+  $MAX_QUERY_RESPONSE_LENGTH_PARAM \
   $MAX_IMPORT_THREADS_PARAM \
   $NOTIFICATION_ADDRESS_PARAM \
   $ENABLE_WEBID_SIGNUP_PARAM \

src/main/java/com/atomgraph/linkeddatahub/Application.java

@@ -24,6 +24,7 @@
 import com.atomgraph.linkeddatahub.server.util.OntologyRepository;
 import org.apache.jena.riot.RDFParser;
 import com.atomgraph.linkeddatahub.server.mapper.HttpHostConnectExceptionMapper;
+import com.atomgraph.linkeddatahub.server.mapper.ResponseContentTooLargeExceptionMapper;
 import com.atomgraph.linkeddatahub.server.mapper.InternalURLExceptionMapper;
 import com.atomgraph.linkeddatahub.server.mapper.MessagingExceptionMapper;
 import com.atomgraph.linkeddatahub.server.mapper.auth.webid.WebIDLoadingExceptionMapper;
@@ -270,6 +271,8 @@ public class Application extends ResourceConfig
     public static final String CLIENT_SEF_PATH = "/static/com/atomgraph/linkeddatahub/xsl/client.xsl.sef.json";
     /** Milliseconds a request waits for a connection from the client pool when nothing configures it; the image sets the same through CONNECTION_REQUEST_TIMEOUT */
     public static final int DEFAULT_CONNECTION_REQUEST_TIMEOUT = 30000;
+    /** Bytes of a SPARQL endpoint query result when nothing configures it; the image sets the same through MAX_QUERY_RESPONSE_LENGTH */
+    public static final int DEFAULT_MAX_QUERY_RESPONSE_LENGTH = 5242880;
     /** ORCID's production environment, used when no issuer is configured; a client registered on the sandbox sets <code>https://sandbox.orcid.org</code> */
     public static final String ORCID_ISSUER = "https://orcid.org";
     /** Path of the client stylesheet source in the webapp, composed with package stylesheets per import set */
@@ -302,6 +305,7 @@ public class Application extends ResourceConfig
     private final boolean allowInternalUrls;
     private final URLValidator urlValidator;
     private final Integer maxContentLength;
+    private final int maxQueryResponseLength;
     private final Address notificationAddress;
     private final Authenticator authenticator;
     private final Properties emailProperties = new Properties();
@@ -378,6 +382,8 @@ public Application(@Context ServletConfig servletConfig) throws URISyntaxExcepti
             System.getProperty("com.atomgraph.linkeddatahub.allowInternalUrls") != null ? Boolean.parseBoolean(System.getProperty("com.atomgraph.linkeddatahub.allowInternalUrls")) :
             servletConfig.getServletContext().getInitParameter(LDHC.allowInternalUrls.getURI()) != null ? Boolean.parseBoolean(servletConfig.getServletContext().getInitParameter(LDHC.allowInternalUrls.getURI())) : false,
             servletConfig.getServletContext().getInitParameter(LDHC.maxContentLength.getURI()) != null ? Integer.valueOf(servletConfig.getServletContext().getInitParameter(LDHC.maxContentLength.getURI())) : null,
+            servletConfig.getServletContext().getInitParameter(LDHC.maxQueryResponseLength.getURI()) != null ? Integer.parseInt(servletConfig.getServletContext().getInitParameter(LDHC.maxQueryResponseLength.getURI())) :
+            DEFAULT_MAX_QUERY_RESPONSE_LENGTH, // unset means the endpoint buffers, and a page renders, a result of any length
             System.getProperty("com.atomgraph.linkeddatahub.maxConnPerRoute") != null ? Integer.valueOf(System.getProperty("com.atomgraph.linkeddatahub.maxConnPerRoute")) :
             servletConfig.getServletContext().getInitParameter(LDHC.maxConnPerRoute.getURI()) != null ? Integer.valueOf(servletConfig.getServletContext().getInitParameter(LDHC.maxConnPerRoute.getURI())) : null,
             System.getProperty("com.atomgraph.linkeddatahub.maxTotalConn") != null ? Integer.valueOf(System.getProperty("com.atomgraph.linkeddatahub.maxTotalConn")) :
@@ -449,6 +455,7 @@ public Application(@Context ServletConfig servletConfig) throws URISyntaxExcepti
      * @param enableAssistant true if the assistant's plan service is deployed beside this instance
      * @param allowInternalUrls true if internal/private network URLs are allowed (disables SSRF protection)
      * @param maxContentLength maximum size of request entity
+     * @param maxQueryResponseLength maximum length of a SPARQL endpoint query result in bytes
      * @param maxConnPerRoute maximum client connections per rout
      * @param maxTotalConn maximum total client connections
      * @param maxRequestRetries maximum number of times that the HTTP client will retry a request
@@ -480,7 +487,7 @@ public Application(final ServletConfig servletConfig, final MediaTypes mediaType
             final String webIDQueryString, final String agentQueryString, final String userAccountQueryString, final String ontologyQueryString,
             final String baseURIString, final String proxyScheme, final String proxyHostname, final Integer proxyPort,
             final String uploadRootString, final String sefRootString, final String sefCompilerString, final String clientStylesheetString, final boolean invalidateCache,
-            final Integer cookieMaxAge, final boolean enableLinkedDataProxy, final boolean enableAssistant, final boolean allowInternalUrls, final Integer maxContentLength,
+            final Integer cookieMaxAge, final boolean enableLinkedDataProxy, final boolean enableAssistant, final boolean allowInternalUrls, final Integer maxContentLength, final int maxQueryResponseLength,
             final Integer maxConnPerRoute, final Integer maxTotalConn, final Integer maxRequestRetries, final Integer connectionRequestTimeout,
             final Integer socketTimeout, final Integer connectTimeout, final Integer selfRequestTimeout, final Long connectionTimeToLive, final Integer validateAfterInactivity, final Integer maxImportThreads,
             final String notificationAddressString, final boolean enableWebIDSignUp, final String oidcRefreshTokensPropertiesPath,
@@ -622,6 +629,7 @@ public Application(final ServletConfig servletConfig, final MediaTypes mediaType
         this.urlValidator = new URLValidator(allowInternalUrls);
         configureServiceExecution(allowInternalUrls);
         this.maxContentLength = maxContentLength;
+        this.maxQueryResponseLength = maxQueryResponseLength;
         this.invalidateCache = invalidateCache;
         this.enableWebIDSignUp = enableWebIDSignUp;
         this.oidcRefreshTokensPropertiesPath = oidcRefreshTokensPropertiesPath;
@@ -1288,6 +1296,7 @@ protected void registerExceptionMappers()
         register(NotAcceptableExceptionMapper.class);
         register(ClientErrorExceptionMapper.class);
         register(HttpHostConnectExceptionMapper.class);
+        register(ResponseContentTooLargeExceptionMapper.class);
         register(InternalURLExceptionMapper.class);
         register(BadGatewayExceptionMapper.class);
         register(OntClassNotFoundExceptionMapper.class);
@@ -2514,6 +2523,16 @@ public Integer getMaxContentLength()
         return maxContentLength;
     }
 
+    /**
+     * Maximum length of the result the SPARQL endpoint answers a query with.
+     * 
+     * @return length in bytes
+     */
+    public int getMaxQueryResponseLength()
+    {
+        return maxQueryResponseLength;
+    }
+
     /**
      * Keystore of the HTTP client.
      * 

src/main/java/com/atomgraph/linkeddatahub/client/exception/ResponseContentTooLargeException.java

@@ -33,9 +33,10 @@ public class ResponseContentTooLargeException extends WebApplicationException
      * @param maxContentLength maximum content length in bytes
      * @param contentLength actual content length in bytes
      */
-    public ResponseContentTooLargeException(long maxContentLength, long contentLength) // TO-DO: use sizes to generate a message?
+    public ResponseContentTooLargeException(long maxContentLength, long contentLength)
     {
-        super(Response.Status.BAD_GATEWAY);
+        // a streamed response is refused once it passes the limit, so its count is where it stopped, not its length
+        super("Response is larger than the limit of " + maxContentLength + " bytes", Response.Status.BAD_GATEWAY);
     }
 
 }

src/main/java/com/atomgraph/linkeddatahub/client/filter/ResponseLengthLimitFilter.java

@@ -0,0 +1,77 @@
+/**
+ *  Copyright 2026 Martynas Jusevičius <martynas@atomgraph.com>
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ */
+package com.atomgraph.linkeddatahub.client.filter;
+
+import com.atomgraph.linkeddatahub.server.filter.request.ContentLengthLimitFilter;
+import java.io.IOException;
+import jakarta.ws.rs.client.ClientRequestContext;
+import jakarta.ws.rs.client.ClientRequestFilter;
+import jakarta.ws.rs.client.ClientResponseContext;
+import jakarta.ws.rs.client.ClientResponseFilter;
+
+/**
+ * Client filter that bounds a request's response with a limit of its own, in place of the configured one.
+ * <p>
+ * The configured limit ({@link ContentLengthLimitFilter}) bounds content from origins nobody controls, and
+ * this deployment's own store is exempt from it ({@link UnlimitedContentLengthFilter}). A query result
+ * answered to an HTTP caller of the SPARQL endpoint is bounded for a different reason: the endpoint
+ * buffers it whole, and so does whatever receives it - a page renders it in the browser's only thread.
+ * That bound is not the configured one, which is a limit on input. So the request carries its own,
+ * which the configured filter on the same client honours, and this filter applies it itself for a
+ * client without one.
+ *
+ * @author {@literal Martynas Jusevičius <martynas@atomgraph.com>}
+ * @see ContentLengthLimitFilter#MAX_CONTENT_LENGTH
+ */
+public class ResponseLengthLimitFilter implements ClientRequestFilter, ClientResponseFilter
+{
+
+    private final ContentLengthLimitFilter limitFilter;
+
+    /**
+     * Constructs filter.
+     *
+     * @param maxContentLength maximum response length in bytes
+     */
+    public ResponseLengthLimitFilter(int maxContentLength)
+    {
+        this.limitFilter = new ContentLengthLimitFilter(maxContentLength);
+    }
+
+    @Override
+    public void filter(ClientRequestContext requestContext) throws IOException
+    {
+        requestContext.setProperty(ContentLengthLimitFilter.MAX_CONTENT_LENGTH, getLimitFilter().getMaxContentLength());
+    }
+
+    @Override
+    public void filter(ClientRequestContext requestContext, ClientResponseContext responseContext) throws IOException
+    {
+        getLimitFilter().filter(requestContext, responseContext);
+    }
+
+    /**
+     * Returns the filter that applies the limit.
+     *
+     * @return content length limit filter
+     */
+    public ContentLengthLimitFilter getLimitFilter()
+    {
+        return limitFilter;
+    }
+
+}

src/main/java/com/atomgraph/linkeddatahub/model/ServiceContext.java

@@ -22,8 +22,10 @@
 import com.atomgraph.core.client.SPARQLClient;
 import com.atomgraph.core.model.EndpointAccessor;
 import com.atomgraph.core.model.impl.remote.EndpointAccessorImpl;
+import com.atomgraph.linkeddatahub.client.filter.ResponseLengthLimitFilter;
 import com.atomgraph.linkeddatahub.client.filter.UnlimitedContentLengthFilter;
 import jakarta.ws.rs.client.Client;
+import jakarta.ws.rs.client.ClientRequestFilter;
 import jakarta.ws.rs.client.WebTarget;
 import jakarta.ws.rs.core.UriBuilder;
 import java.net.URI;
@@ -105,6 +107,20 @@ public SPARQLClient getSPARQLClient()
      * @return SPARQL client
      */
     public SPARQLClient getSPARQLClient(WebTarget webTarget)
+    {
+        // this service is this deployment's own store, not an origin the content limit is meant to bound.
+        // Registered per client rather than taken off the outbound client, which also dereferences WebIDs
+        return getSPARQLClient(webTarget, new UnlimitedContentLengthFilter());
+    }
+
+    /**
+     * Creates a SPARQL Protocol client for the specified URI web target, its responses bounded by the given filter.
+     *
+     * @param webTarget URI web target
+     * @param lengthFilter filter that sets the response length limit
+     * @return SPARQL client
+     */
+    protected SPARQLClient getSPARQLClient(WebTarget webTarget, ClientRequestFilter lengthFilter)
     {
         SPARQLClient sparqlClient;
 
@@ -113,9 +129,7 @@ public SPARQLClient getSPARQLClient(WebTarget webTarget)
         else
             sparqlClient = SPARQLClient.create(getMediaTypes(), webTarget);
 
-        // this service is this deployment's own store, not an origin the content limit is meant to bound.
-        // Registered per client rather than taken off the outbound client, which also dereferences WebIDs
-        sparqlClient.getEndpoint().register(new UnlimitedContentLengthFilter());
+        sparqlClient.getEndpoint().register(lengthFilter);
 
         if (getService().getAuthUser() != null && getService().getAuthPwd() != null)
         {
@@ -139,6 +153,20 @@ public EndpointAccessor getEndpointAccessor()
         return new EndpointAccessorImpl(getSPARQLClient());
     }
 
+    /**
+     * Returns the endpoint accessor that answers HTTP callers of this service's SPARQL endpoint.
+     * Unlike {@link #getEndpointAccessor()}, which the platform's own lookups use, a result longer than the
+     * given limit is refused: the endpoint buffers it whole, and so does whatever receives it.
+     *
+     * @param maxResponseLength maximum length of the store's response in bytes
+     * @return endpoint accessor
+     */
+    public EndpointAccessor getQueryEndpointAccessor(int maxResponseLength)
+    {
+        return new EndpointAccessorImpl(getSPARQLClient(getClient().target(getProxiedURI(URI.create(getService().getSPARQLEndpoint().getURI()))),
+            new ResponseLengthLimitFilter(maxResponseLength)));
+    }
+
     /**
      * Returns the Graph Store Protocol client for this service, with proxy routing applied.
      *