testcontainers/testcontainers-java · error · SolrClientUtilsException

Unable to upload binary

Error message

Unable to upload binary
${responseBody}

What it means

SolrClientUtils.executePost performs an HTTP POST (file upload) to the running Solr container using OkHttp. When the response is not successful, it reads the body and throws SolrClientUtilsException with message 'Unable to upload binary' plus the response body. Called by uploadConfiguration and createCollection.

Solutions

1. Read the responseBody appended to the exception message — it usually contains Solr's own error explaining the rejection.
2. Ensure the container is fully started before calling uploadConfiguration/createCollection (Testcontainers wait strategy should cover this; add wait checks if using manually).
3. Validate the configuration zip structure (solrconfig.xml, schema files at zip root or under conf/).
4. Check the collection name doesn't already exist or delete it first; use a unique name per test run.
5. Enable OkHttp/Solr request logging to inspect the exact request URL and payload if the body message is vague.

Example fix

// before
try {
    SolrClientUtils.uploadConfiguration(container, "myconfig", Paths.get("bad-config.zip"));
} catch (SolrClientUtilsException e) {
    // ignore
}
// after
try {
    SolrClientUtils.uploadConfiguration(container, "myconfig", Paths.get("conf.zip"));
} catch (SolrClientUtilsException e) {
    LOGGER.error("Solr returned code {} body: {}", e.getStatusCode(), e.getMessage(), e);
    throw e;
}

// before calling
if (!container.isRunning()) throw new IllegalStateException("Solr container not started");
if (configZip == null || !Files.exists(configZip)) throw new IllegalStateException("Config zip missing: " + configZip);

try {
  SolrClientUtils.uploadConfiguration(container, name, zipPath);
  SolrClientUtils.createCollection(container, name);
} catch (SolrClientUtilsException e) {
  LOGGER.error("Solr utils failed with HTTP {}: {}", e.getStatusCode(), e.getMessage(), e);
  throw e;
}

When it happens

Trigger: uploadConfiguration() or createCollection() failing server-side: Solr API rejecting the config zip, bad collection name, ZooKeeper issues, or hitting the wrong port/path, producing a non-2xx response.

Common situations: Uploading a malformed/oversized configset zip, creating a collection that already exists, Solr not fully started yet, wrong Solr version API differences, network/DNS issues inside the container network.

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

• Collection name must not be empty
• Collection name must not be empty
• Could not perform request against couchbase HTTP endpoint
• HTTP response code was
• message: response, body=body

AI-assisted analysis of testcontainers/testcontainers-java@8e549514e3 (2026-09-12). Data as JSON: /api/errors/a6c816b8cd3e4f09. Report an issue: GitHub.

Appendix: source

Thrown at modules/solr/src/main/java/org/testcontainers/containers/SolrClientUtils.java:91

        }
        HttpUrl url = generateSolrURL(hostname, port, Arrays.asList("admin", "collections"), parameters);
        executePost(url, null);
    }

    private static void executePost(HttpUrl url, byte[] data) throws IOException {
        RequestBody requestBody = data == null
            ? RequestBody.create(MediaType.parse("text/plain"), "")
            : RequestBody.create(MediaType.parse("application/octet-stream"), data);
        Request request = new Request.Builder().url(url).post(requestBody).build();

        Response response = httpClient.newCall(request).execute();
        if (!response.isSuccessful()) {
            String responseBody = "";
            if (response.body() != null) {
                responseBody = response.body().string();
                response.close();
            }
            throw new SolrClientUtilsException(response.code(), "Unable to upload binary\n" + responseBody);
        }
        if (response.body() != null) {
            response.close();
        }
    }

    private static HttpUrl generateSolrURL(
        String hostname,
        int port,
        List<String> pathSegments,
        Map<String, String> parameters
    ) throws URISyntaxException {
        HttpUrl.Builder builder = new HttpUrl.Builder();
        builder.scheme("http");
        builder.host(hostname);
        builder.port(port);
        // Path
        builder.addPathSegment("solr");

View on GitHub (pinned to 8e549514e3)