{"record":{"id":"d77fe081f62a308e","repo":"testcontainers/testcontainers-java","slug":"container-needs-to-be-initialized","errorCode":null,"errorMessage":"Container {} needs to be initialized","messagePattern":"Container (.+?) needs to be initialized","errorType":"exception","errorClass":"ExtensionConfigurationException","httpStatus":null,"severity":"error","filePath":"modules/junit-jupiter/src/main/java/org/testcontainers/junit/jupiter/TestcontainersExtension.java","lineNumber":250,"sourceCode":"                boolean isStartable = Startable.class.isAssignableFrom(field.getType());\n\n                if (!isStartable) {\n                    throw new ExtensionConfigurationException(\n                        String.format(\"FieldName: %s does not implement Startable\", field.getName())\n                    );\n                }\n                return true;\n            }\n            return false;\n        };\n    }\n\n    private static StoreAdapter getContainerInstance(final Object testInstance, final Field field) {\n        try {\n            field.setAccessible(true);\n            Startable containerInstance = (Startable) field.get(testInstance);\n            if (containerInstance == null) {\n                throw new ExtensionConfigurationException(\"Container \" + field.getName() + \" needs to be initialized\");\n            }\n            return new StoreAdapter(field.getDeclaringClass(), field.getName(), containerInstance);\n        } catch (IllegalAccessException e) {\n            throw new ExtensionConfigurationException(\"Can not access container defined in field \" + field.getName());\n        }\n    }\n\n    /**\n     * An adapter for {@link Startable} that implement {@link CloseableResource}\n     * thereby letting the JUnit automatically stop containers once the current\n     * {@link ExtensionContext} is closed.\n     */\n    private static class StoreAdapter implements CloseableResource, AutoCloseable {\n\n        @Getter\n        private String key;\n\n        private Startable container;","sourceCodeStart":232,"sourceCodeEnd":268,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/modules/junit-jupiter/src/main/java/org/testcontainers/junit/jupiter/TestcontainersExtension.java#L232-L268","documentation":"Thrown by the JUnit Jupiter extension when a field annotated with @Container is null at the moment the extension inspects the test instance. The extension requires every container field to be assigned before lifecycle callbacks run, because it must wrap the instance in a StoreAdapter for shared lifecycle management. It is a configuration error in the test class, not a runtime/container failure.","triggerScenarios":"A @Container field is declared but never initialized (stays null) when beforeEach/allCallback methods call findSharedContainers or findRestartContainers, which call getContainerInstance.","commonSituations":"Declaring 'static GenericContainer<?> container;' and initializing it inside a @BeforeEach method that runs after the extension reads the field; typo in initializer or conditional initialization; initialization moved to @BeforeAll but field read earlier by a parent extension.","solutions":["Initialize the container field inline at declaration (e.g. 'static final GenericContainer<?> REDIS = new GenericContainer(\"redis:7\")')","If initialization must be dynamic, do it in a static initializer block or @BeforeAll that runs before the extension callback","Verify the field is not shadowed or accidentally reset to null elsewhere in the test class"],"exampleFix":"// before\n@Container\nstatic GenericContainer<?> redis;\n\n@BeforeAll\nstatic void init() { redis = new GenericContainer<>(\"redis:7\"); }\n\n// after\n@Container\nstatic GenericContainer<?> redis = new GenericContainer<>(\"redis:7\").withExposedPorts(6379);","handlingStrategy":"validation","validationCode":"// in test setup, before running\nfor (Field f : testClass.getDeclaredFields()) {\n  if (f.isAnnotationPresent(Container.class)) {\n    f.setAccessible(true);\n    if (f.get(null /* or instance */) == null)\n      throw new IllegalStateException(\"Field \" + f.getName() + \" must be initialized inline\");\n  }\n}","typeGuard":"static boolean isInitialized(Object testInstance, Field f) throws IllegalAccessException {\n  f.setAccessible(true);\n  return f.get(testInstance) != null;\n}","tryCatchPattern":null,"preventionTips":["Initialize @Container fields inline at declaration, ideally static final","Never assign container fields inside @BeforeEach/@AfterEach","Keep container creation out of conditionals","Run tests locally before CI to catch ordering issues"],"tags":["junit","testcontainers","configuration"],"backgroundTag":"null-argument","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"}