testcontainers/testcontainers-java · error · InvalidConfigurationException

Invalid value for dockerconfig.source

Error message

Invalid value for dockerconfig.source: %s

What it means

Thrown by EnvironmentAndSystemPropertyClientProviderStrategy when the testcontainers.dockerconfig.source property has a value outside the known set (auto, autoIgnoringUserProperties). The property controls how the Docker client config source is resolved, and unknown values are rejected during strategy initialization.

Solutions

  1. Set testcontainers.dockerconfig.source to a valid value: 'auto' or 'autoIgnoringUserProperties'
  2. Fix typos in the property value (check exact casing)
  3. Remove the property entirely to use the default behavior
  4. Check the testcontainers version docs to confirm which values are supported in your version

Example fix

// before
-Dtestcontainers.dockerconfig.source=autoIgnoreUserProperties
// after
-Dtestcontainers.dockerconfig.source=autoIgnoringUserProperties
Defensive patterns

Strategy: validation

Validate before calling

String src = System.getProperty("testcontainers.dockerconfig.source");
if (src != null && !Set.of("auto", "autoIgnoringUserProperties").contains(src))
    throw new IllegalStateException("Invalid testcontainers.dockerconfig.source: " + src);

Type guard

static boolean isValidDockerConfigSource(String s) {
    return s == null || Set.of("auto", "autoIgnoringUserProperties").contains(s);
}

Try / catch

try {
    // initialization that reads dockerconfig.source
} catch (InvalidConfigurationException e) {
    if (e.getMessage().startsWith("Invalid value for dockerconfig.source")) {
        System.clearProperty("testcontainers.dockerconfig.source"); // fall back to default
    } else throw e;
}

Prevention

When it happens

Trigger: Setting system property or environment variable dockerconfig.source (e.g. -Dtestcontainers.dockerconfig.source=...) to a value other than 'auto' or 'autoIgnoringUserProperties' while the environment-and-system-property strategy initializes its DockerClientConfig.

Common situations: Typo like 'autoIgnoreUserProperties' or 'Auto'; copying a property from a newer/older testcontainers version where allowed values differ; CI configuration with a stale property.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/dockerclient/EnvironmentAndSystemPropertyClientProviderStrategy.java:54

    EnvironmentAndSystemPropertyClientProviderStrategy(DefaultDockerClientConfig.Builder configBuilder) {
        String dockerConfigSource = TestcontainersConfiguration
            .getInstance()
            .getEnvVarOrProperty("dockerconfig.source", "auto");

        switch (dockerConfigSource) {
            case "auto":
                Optional<String> dockerHost = getSetting("docker.host");
                dockerHost.ifPresent(configBuilder::withDockerHost);
                applicable = dockerHost.isPresent();
                getSetting("docker.tls.verify").ifPresent(configBuilder::withDockerTlsVerify);
                getSetting("docker.cert.path").ifPresent(configBuilder::withDockerCertPath);
                break;
            case "autoIgnoringUserProperties":
                applicable = configBuilder.isDockerHostSetExplicitly();
                break;
            default:
                throw new InvalidConfigurationException("Invalid value for dockerconfig.source: " + dockerConfigSource);
        }

        dockerClientConfig = configBuilder.build();
    }

    private Optional<String> getSetting(final String name) {
        return Optional.ofNullable(TestcontainersConfiguration.getInstance().getEnvVarOrUserProperty(name, null));
    }

    @Override
    public TransportConfig getTransportConfig() {
        return TransportConfig
            .builder()
            .dockerHost(dockerClientConfig.getDockerHost())
            .sslConfig(dockerClientConfig.getSSLConfig())
            .build();
    }

View on GitHub (pinned to 8e549514e3)