testcontainers/testcontainers-java · error · ContainerLaunchException

Exception while trying to create temp directory

Error message

Exception while trying to create temp directory

What it means

During BrowserWebDriverContainer.configure(), if no VNC recording directory was set, Testcontainers creates a temp directory via Files.createTempDirectory. If that fails with an IOException, it logs the error and rethrows as ContainerLaunchException with this message, aborting container startup.

Solutions

1. Call withRecordingDirectory(new File("/some/writable/path")) explicitly so temp creation is skipped.
2. Verify java.io.tmpdir points to an existing, writable directory; set -Djava.io.tmpdir=/tmp if misconfigured.
3. Free disk space / fix permissions on the temp directory in the CI environment.
4. Migrate to the newer org.testcontainers.selenium.BrowserWebDriverContainer (Selenium module) which has the same guard — the fix applies identically.
5. Catch ContainerLaunchException around container.start() to surface the cause IOException in test diagnostics.

Example fix

// before
BrowserWebDriverContainer container = new BrowserWebDriverContainer()
    .withRecordingFileFactory(...); // no directory set, relies on /tmp
// after
BrowserWebDriverContainer container = new BrowserWebDriverContainer()
    .withRecordingDirectory(new File("/tmp/vnc-recordings"))
    .withRecordingFileFactory(...);

File vncDir = new File(System.getProperty("java.io.tmpdir"), "vnc-recordings");
if (!vncDir.canWrite() && !vncDir.mkdirs()) {
  throw new IllegalStateException("Cannot write VNC recording dir: " + vncDir);
}
container.withRecordingDirectory(vncDir);

try {
  container.start();
} catch (ContainerLaunchException e) {
  if (e.getMessage() != null && e.getMessage().contains("create temp directory")) {
    logger.error("Temp dir creation failed; check java.io.tmpdir permissions/disk space", e.getCause()); }
  throw e;
}

When it happens

Trigger: Calling withRecordingFileFactory/starting a BrowserWebDriverContainer (deprecated module) without withRecordingDirectory when java.io.tmpdir is unwritable, full, or a security manager blocks temp file creation.

Common situations: Read-only /tmp in CI containers, disk-full build agents, custom -Djava.io.tmpdir pointing to a non-existent or permission-restricted path, SELinux/AppArmor restrictions.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Exception while trying to create temp directory
• Containerised Docker Compose exited abnormally with code
• Error running local Docker Compose command
• Failed to process JAR file when extracting classpath…
• Could not load classpath init script

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

Appendix: source

Thrown at modules/selenium/src/main/java/org/testcontainers/containers/BrowserWebDriverContainer.java:179

        if (recordingMode == VncRecordingMode.SKIP) {
            return ImmutableSet.of(seleniumPort);
        } else {
            return ImmutableSet.of(seleniumPort, getMappedPort(VNC_PORT));
        }
    }

    @Override
    protected void configure() {
        String seleniumVersion = SeleniumUtils.determineClasspathSeleniumVersion();

        if (recordingMode != VncRecordingMode.SKIP) {
            if (vncRecordingDirectory == null) {
                try {
                    vncRecordingDirectory = Files.createTempDirectory(TC_TEMP_DIR_PREFIX).toFile();
                } catch (IOException e) {
                    // should never happen as per javadoc, since we use valid prefix
                    logger().error("Exception while trying to create temp directory", e);
                    throw new ContainerLaunchException("Exception while trying to create temp directory", e);
                }
            }

            if (getNetwork() == null) {
                withNetwork(Network.SHARED);
            }

            vncRecordingContainer =
                new VncRecordingContainer(this)
                    .withVncPassword(DEFAULT_PASSWORD)
                    .withVncPort(VNC_PORT)
                    .withVideoFormat(recordingFormat);
        }

        if (customImageName != null) {
            customImageName.assertCompatibleWith(COMPATIBLE_IMAGES);
            super.setDockerImageName(customImageName.asCanonicalNameString());
        } else {

View on GitHub (pinned to 8e549514e3)