{"record":{"id":"ff577f39662752e3","repo":"testcontainers/testcontainers-java","slug":"copyfiletocontainer-can-only-be-used-with-created-running","errorCode":null,"errorMessage":"copyFileToContainer can only be used with created / running container","messagePattern":"copyFileToContainer can only be used with created / running container","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/containers/ContainerState.java","lineNumber":345,"sourceCode":"                \"folder-like containerPath in copyFileToContainer is deprecated, please explicitly specify a file path\"\n            );\n            copyFileToContainer((Transferable) mountableFile, containerPath + sourceFile.getName());\n        } else {\n            copyFileToContainer((Transferable) mountableFile, containerPath);\n        }\n    }\n\n    /**\n     *\n     * Copies a file to the container.\n     *\n     * @param transferable file which is copied into the container\n     * @param containerPath destination path inside the container\n     */\n    @SneakyThrows({ IOException.class, InterruptedException.class })\n    default void copyFileToContainer(Transferable transferable, String containerPath) {\n        if (getContainerId() == null) {\n            throw new IllegalStateException(\"copyFileToContainer can only be used with created / running container\");\n        }\n\n        try (\n            PipedOutputStream pipedOutputStream = new PipedOutputStream();\n            PipedInputStream pipedInputStream = new PipedInputStream(pipedOutputStream);\n            TarArchiveOutputStream tarArchive = new TarArchiveOutputStream(pipedOutputStream)\n        ) {\n            Thread thread = new Thread(() -> {\n                try {\n                    tarArchive.setLongFileMode(TarArchiveOutputStream.LONGFILE_POSIX);\n                    tarArchive.setBigNumberMode(TarArchiveOutputStream.BIGNUMBER_POSIX);\n\n                    transferable.transferTo(tarArchive, containerPath);\n                } finally {\n                    IOUtils.closeQuietly(tarArchive);\n                }\n            });\n","sourceCodeStart":327,"sourceCodeEnd":363,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/ContainerState.java#L327-L363","documentation":"copyFileToContainer streams a file into the container via the Docker API, which requires an existing container ID. If getContainerId() is null (container never created/started) it throws IllegalStateException, since the copy target does not exist yet.","triggerScenarios":"Invoking copyFileToContainer(...) on a GenericContainer instance before start() (or before any start attempt created the container).","commonSituations":"Copying config files in a test setup method before starting the container; copy calls that were reordered after a refactor; containers created with a lifecycle that never reached the created state.","solutions":["Start the container first: call start() (or createContainer in newer APIs) before copyFileToContainer","Alternatively use withCopyFileToContainer(...) as a builder modifier, which Testcontainers applies after container creation automatically","Ensure you're not operating on a fresh GenericContainer object in a helper method","Verify container state with isCreated()/isRunning() if the lifecycle is dynamic"],"exampleFix":"// before\nGenericContainer c = new GenericContainer<>(\"alpine:3\");\nc.copyFileToContainer(Transferable.of(bytes), \"/tmp/a.txt\");\nc.start();\n// after\nGenericContainer c = new GenericContainer<>(\"alpine:3\")\n    .withCopyFileToContainer(Transferable.of(bytes), \"/tmp/a.txt\");\nc.start();","handlingStrategy":"validation","validationCode":"if (container.getContainerId() == null) throw new IllegalStateException(\"start() the container before copyFileToContainer\");","typeGuard":null,"tryCatchPattern":"try { container.copyFileToContainer(t, path); } catch (IllegalStateException e) { if (e.getMessage().startsWith(\"copyFileToContainer\")) { container.start(); container.copyFileToContainer(t, path); } else { throw e; } }","preventionTips":["Prefer withCopyFileToContainer in the builder so ordering is handled for you","Enforce a start-then-interact ordering in test fixtures","Add asserts on isCreated() in helper utilities"],"tags":["container-lifecycle","file-copy","container-state"],"backgroundTag":"invalid-state-transition","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"}