testcontainers/testcontainers-java · error · ContainerLaunchException

Exception while trying to create temp directory

Error message

Exception while trying to create temp directory

What it means

In the newer org.testcontainers.selenium.BrowserWebDriverContainer.configure(), when no VNC recording directory was supplied, a temp directory is created with Files.createTempDirectory. An IOException there is logged and rethrown as ContainerLaunchException 'Exception while trying to create temp directory', failing container start.

Solutions

1. Call withRecordingDirectory(File) with a known-writable path before starting the container.
2. Check/fix the java.io.tmpdir system property and directory permissions.
3. Free disk space on the agent or point TMPDIR to a larger volume.
4. Catch ContainerLaunchException in start-up helper code to record the underlying IOException.

Example fix

// before
BrowserWebDriverContainer container = new BrowserWebDriverContainer("selenium/standalone-chrome:4.9.0");
// after
BrowserWebDriverContainer container = new BrowserWebDriverContainer("selenium/standalone-chrome:4.9.0")
    .withRecordingDirectory(new File("build/vnc-recordings"));

File vncDir = new File("build/vnc-recordings");
if (!vncDir.exists() && !vncDir.mkdirs()) throw new IllegalStateException("Cannot create " + vncDir);
container.withRecordingDirectory(vncDir);

try {
  container.start();
} catch (ContainerLaunchException e) {
  if (e.getMessage() != null && e.getMessage().contains("create temp directory")) {
    throw new IllegalStateException("Set withRecordingDirectory() or fix temp dir permissions", e); }
  throw e;
}

When it happens

Trigger: Starting org.testcontainers.selenium.BrowserWebDriverContainer with recording enabled but without withRecordingDirectory when the temp directory cannot be created (unwritable/full java.io.tmpdir).

Common situations: Read-only or full /tmp in CI, custom -Djava.io.tmpdir to a missing path, sandboxed/SELinux-restricted build agents.

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/a7a827d3e72699d7. Report an issue: GitHub.

Appendix: source

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

    protected Set<Integer> getLivenessCheckPorts() {
        Integer seleniumPort = getMappedPort(SELENIUM_PORT);
        if (recordingMode == VncRecordingMode.SKIP) {
            return ImmutableSet.of(seleniumPort);
        } else {
            return ImmutableSet.of(seleniumPort, getMappedPort(VNC_PORT));
        }
    }

    @Override
    protected void configure() {
        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);
        }

        String timeZone = System.getProperty("user.timezone");

        if (timeZone == null || timeZone.isEmpty()) {
            timeZone = "Etc/UTC";

View on GitHub (pinned to 8e549514e3)