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

Can't serialize arguments

Error message

Can't serialize arguments: ${args}

What it means

MultiArgsStatement.appendArguments serializes the statement's args array to JSON with Jackson and appends it to the Dockerfile. If Jackson cannot serialize the args, it throws a RuntimeException naming the args. This happens when an argument is of a type Jackson has no serializer for.

Solutions

1. Convert all args to Strings before constructing the statement (String.valueOf or explicit formatting).
2. Check the args array printed in the message for the non-serializable element.
3. If a complex type is intentional, ensure it's plain-data (records/POJOs with getters) or register the needed Jackson module.

Example fix

// before
new MultiArgsStatement("CMD", new Object[]{ Path.of("/app/run.sh") });
// after
new MultiArgsStatement("CMD", new Object[]{ "/app/run.sh" });

for (Object arg : args) {
    if (arg != null && !(arg instanceof String || arg instanceof Number || arg instanceof Boolean)) {
        throw new IllegalArgumentException("CMD/ENTRYPOINT arg must be a simple value: " + arg);
    }
}

static boolean isSimpleArg(Object a) {
    return a instanceof String || a instanceof Number || a instanceof Boolean;
}

try {
    statement.appendArguments(sb);
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Can't serialize arguments")) {
        log.error("MultiArgsStatement args not JSON-serializable", e);
    }
    throw e;
}

When it happens

Trigger: Using a MultiArgsStatement-derived Dockerfile instruction (e.g. CMD, ENTRYPOINT, COPY with args) with elements that are not Strings/simple values — custom objects, unregistered date/time types, or types without Jackson serializers.

Common situations: Building a Dockerfile programmatically and passing runtime objects (URI, Path, nested POJOs) as command args; changing arg types after refactoring; Jackson version upgrades removing implicit serializers.

Understand the failure class

Background: "JSON serialization failed", "not JSON serializable", "Failed to serialize": why JSON marshaling errors happen and how to fix them — this error's family across 46 libraries.

Related errors

• Can't serialize entry
• Failed to convert arguments into json
• overriding previous mapping for
• Tried to parse Dockerfile at path
• Unable to read Dockerfile at path

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/images/builder/dockerfile/statement/MultiArgsStatement.java:24

import java.util.Arrays;

public class MultiArgsStatement extends Statement {

    private static final ObjectMapper objectMapper = new ObjectMapper();

    protected final String[] args;

    public MultiArgsStatement(String type, String... args) {
        super(type);
        this.args = args;
    }

    @Override
    public void appendArguments(StringBuilder dockerfileStringBuilder) {
        try {
            dockerfileStringBuilder.append(objectMapper.writeValueAsString(args));
        } catch (JsonProcessingException e) {
            throw new RuntimeException("Can't serialize arguments: " + Arrays.toString(args), e);
        }
    }
}

View on GitHub (pinned to 8e549514e3)