{"record":{"id":"3ece9a3328971f74","repo":"testcontainers/testcontainers-java","slug":"can-t-transfer-description","errorCode":null,"errorMessage":"Can't transfer ${description}","messagePattern":"Can't transfer (.+?)","errorType":"exception","errorClass":"java.lang.RuntimeException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/images/builder/Transferable.java","lineNumber":85,"sourceCode":"    long getSize();\n\n    /**\n     * transfer content of this Transferable to the output stream. <b>Must not</b> close the stream.\n     *\n     * @param tarArchiveOutputStream stream to output\n     * @param destination\n     */\n    default void transferTo(TarArchiveOutputStream tarArchiveOutputStream, final String destination) {\n        TarArchiveEntry tarEntry = new TarArchiveEntry(destination);\n        tarEntry.setSize(getSize());\n        tarEntry.setMode(getFileMode());\n\n        try {\n            tarArchiveOutputStream.putArchiveEntry(tarEntry);\n            IOUtils.write(getBytes(), tarArchiveOutputStream);\n            tarArchiveOutputStream.closeArchiveEntry();\n        } catch (IOException e) {\n            throw new RuntimeException(\"Can't transfer \" + getDescription(), e);\n        }\n    }\n\n    default byte[] getBytes() {\n        return new byte[0];\n    }\n\n    default String getDescription() {\n        return \"\";\n    }\n\n    default void updateChecksum(Checksum checksum) {\n        throw new UnsupportedOperationException(\"Provide implementation in subclass\");\n    }\n}\n","sourceCodeStart":67,"sourceCodeEnd":101,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/images/builder/Transferable.java#L67-L101","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the <description> in the message and confirm the source file/resource exists and is readable","For classpath resources, verify the file is packaged (in src/test/resources / target/classes), not just in source","Fix filesystem permissions on the host file","Run `docker info`/daemon health checks if the tar stream to the daemon is failing","Upgrade testcontainers if the cause shows a tar/docker-java stream bug"],"exampleFix":"// before\nMountableFile.forClasspathResource(\"config/app.yml\"); // not on classpath -> Can't transfer\n// after\nMountableFile.forClasspathResource(\"config/app.yml\"); // file moved to src/test/resources/config/app.yml","handlingStrategy":"validation","validationCode":"// validate the transferable source exists before transfer\njava.nio.file.Path p = java.nio.file.Path.of(hostPath);\nif (!java.nio.file.Files.isReadable(p)) {\n    throw new IllegalStateException(\"Not readable, transfer would fail: \" + hostPath);\n}","typeGuard":"null","tryCatchPattern":"try {\n    container.withCopyFileToContainer(mountableFile, \"/app/config.yml\").start();\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Can't transfer\")) {\n        throw new IllegalStateException(\"Check source path/classpath resource: \" + e.getMessage(), e);\n    }\n    throw e;\n}","preventionTips":["For forClasspathResource, confirm the resource is packaged into the test classpath output","Prefer absolute host paths via forHostPath and verify existence first","Don't delete/modify source files while containers are being built/started","Check read permissions on host files in CI containers"],"tags":["docker","tar","file-transfer","classpath"],"backgroundTag":"file-read-failed","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}