testcontainers/testcontainers-java · error · IllegalStateException

Solr needs to have a configuration if you want to use a…

Error message

Solr needs to have a configuration if you want to use a schema

What it means

Testcontainers' SolrContainer requires a Solr configuration (solrconfig.xml) whenever a custom schema is supplied, because Solr cores are created from a configset that bundles both files. Thrown from configure() at container start when getSolrSchema() is set but getSolrConfiguration() is null.

Solutions

1. Add a withConfiguration(name, url-to-solrconfig.xml) call alongside withSchema.
2. If you don't need a custom solrconfig, use the default configset (_default) and drop the schema override.
3. Bundle both files in a configset directory and reference them together.

Example fix

// before
new SolrContainer(DockerImageName.parse("solr:8"))
    .withCollection("items")
    .withSchema(new File("schema.xml").toURI().toURL());
// after
new SolrContainer(DockerImageName.parse("solr:8"))
    .withCollection("items")
    .withConfiguration("custom", new File("solrconfig.xml").toURI().toURL())
    .withSchema(new File("schema.xml").toURI().toURL());

assert container.getSolrSchema() == null || container.getSolrConfiguration() != null : "withSchema requires withConfiguration";

When it happens

Trigger: Calling withSolrSchema(...) (or withSchema) without a preceding withConfiguration(...) before starting the container.

Common situations: Developers customize the schema for custom fields but assume a default solrconfig.xml is generated; copying config code from examples that only set the configuration and forgetting it works both ways.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Solr needs to have a configuration if you want to use a…
• Changing startup timeout is not supported with mode
• Unexpected scheme
• Setting a in not supported in the versions below 22.1.0
• The provided service (service) has no quota to configure

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

Appendix: source

Thrown at modules/solr/src/main/java/org/testcontainers/containers/SolrContainer.java:107

    public SolrContainer withSchema(URL schema) {
        configuration.setSolrSchema(schema);
        return self();
    }

    public int getSolrPort() {
        return getMappedPort(SOLR_PORT);
    }

    public int getZookeeperPort() {
        return getMappedPort(ZOOKEEPER_PORT);
    }

    @Override
    @SneakyThrows
    protected void configure() {
        if (configuration.getSolrSchema() != null && configuration.getSolrConfiguration() == null) {
            throw new IllegalStateException("Solr needs to have a configuration if you want to use a schema");
        }
        // Generate Command Builder
        String command = "solr start -f";
        // Add Default Ports
        this.addExposedPort(SOLR_PORT);

        // Configure Zookeeper
        if (configuration.isZookeeper()) {
            this.addExposedPort(ZOOKEEPER_PORT);
            if (this.imageVersion.isGreaterThanOrEqualTo("9.7.0")) {
                command = "-DzkRun --host localhost";
            } else {
                command = "-DzkRun -h localhost";
            }
        }

        // Apply generated Command
        this.setCommand(command);

View on GitHub (pinned to 8e549514e3)