testcontainers/testcontainers-java · error · java.lang.RuntimeException

Can't transfer

Error message

Can't transfer ${description}

What it means

Transferable.transferTo() writes this item (a file/directory/classpath resource) into the tar archive stream used for docker cp / image build contexts. Any IOException during tar entry writing is wrapped as RuntimeException("Can't transfer <description>"). It means the content could not be read or written into the tar archive.

Solutions

1. Check the <description> in the message and confirm the source file/resource exists and is readable
2. For classpath resources, verify the file is packaged (in src/test/resources / target/classes), not just in source
3. Fix filesystem permissions on the host file
4. Run `docker info`/daemon health checks if the tar stream to the daemon is failing
5. Upgrade testcontainers if the cause shows a tar/docker-java stream bug

Example fix

// before
MountableFile.forClasspathResource("config/app.yml"); // not on classpath -> Can't transfer
// after
MountableFile.forClasspathResource("config/app.yml"); // file moved to src/test/resources/config/app.yml

// validate the transferable source exists before transfer
java.nio.file.Path p = java.nio.file.Path.of(hostPath);
if (!java.nio.file.Files.isReadable(p)) {
    throw new IllegalStateException("Not readable, transfer would fail: " + hostPath);
}

null

try {
    container.withCopyFileToContainer(mountableFile, "/app/config.yml").start();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Can't transfer")) {
        throw new IllegalStateException("Check source path/classpath resource: " + e.getMessage(), e);
    }
    throw e;
}

When it happens

Trigger: MountableFile/other Transferable being transferred into a container or build context whose source bytes cannot be read (missing file, unreadable path) or the tar stream itself fails mid-write.

Common situations: MountableFile pointing at a classpath resource that isn't on the classpath; source file deleted between check and transfer; permission issues reading the host file; very large files causing stream failure.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• You should never close the global DockerClient!
• Check failed:
• Requested port ( ) is not mapped
• execInContainer can only be used while the Container is…
• Container startup failed for image

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/images/builder/Transferable.java:85

    long getSize();

    /**
     * transfer content of this Transferable to the output stream. <b>Must not</b> close the stream.
     *
     * @param tarArchiveOutputStream stream to output
     * @param destination
     */
    default void transferTo(TarArchiveOutputStream tarArchiveOutputStream, final String destination) {
        TarArchiveEntry tarEntry = new TarArchiveEntry(destination);
        tarEntry.setSize(getSize());
        tarEntry.setMode(getFileMode());

        try {
            tarArchiveOutputStream.putArchiveEntry(tarEntry);
            IOUtils.write(getBytes(), tarArchiveOutputStream);
            tarArchiveOutputStream.closeArchiveEntry();
        } catch (IOException e) {
            throw new RuntimeException("Can't transfer " + getDescription(), e);
        }
    }

    default byte[] getBytes() {
        return new byte[0];
    }

    default String getDescription() {
        return "";
    }

    default void updateChecksum(Checksum checksum) {
        throw new UnsupportedOperationException("Provide implementation in subclass");
    }
}

View on GitHub (pinned to 8e549514e3)