aeron-io/aeron · error · IllegalArgumentException

Unknown thread naming mode

Error message

Unknown thread naming mode: <mode>

What it means

Aeron names its internal threads according to the aeron.thread.name.mode system property ('classic' or 'new'). An unknown value for this property causes threadName to throw an IllegalArgumentException.

Solutions

1. Set -Daeron.thread.name.mode to exactly "classic" or "new" (see CommonContext.THREAD_NAMING_CLASSIC / THREAD_NAMING_NEW)
2. Remove the aeron.thread.name.mode property to fall back to the default
3. Check for stray whitespace or case differences in the property value

Example fix

// before
-Daeron.thread.name.mode=New

// after
-Daeron.thread.name.mode=new

String mode = System.getProperty("aeron.thread.name.mode", "");
if (!mode.isEmpty() && !mode.equals("classic") && !mode.equals("new")) {
    throw new IllegalArgumentException("aeron.thread.name.mode must be 'classic' or 'new', got: " + mode);
}

When it happens

Trigger: Setting -Daeron.thread.name.mode to any string other than CLASSIC or NEW (e.g. a typo like 'Classic' or 'legacy') before creating an Aeron client or driver.

Common situations: Typo in JVM system property or environment config; copying a property value from documentation of a different library; case-sensitive value mismatch.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Aeron client instance must set…
• Aeron client must use a RethrowingErrorHandler
• Aeron client must use a RethrowingErrorHandler
• AeronArchive.Context.controlRequestChannel must be set
• AeronArchive.Context.controlResponseChannel must be set

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/1fe9dca8e31ccea9. Report an issue: GitHub.

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/CommonContext.java:564

     */
    public static final String THREAD_NAMING_DEFAULT = THREAD_NAMING_CLASSIC;


    /**
     * Choose a thread/role name depending on the configured naming scheme.
     *
     * @param newName the new, prefixed name.
     * @param classicName  the old name.
     * @return the name to use for the current naming scheme.
     */
    public static String threadName(final String newName, final String classicName)
    {
        final String mode = System.getProperty(THREAD_NAMING_PROP_NAME, THREAD_NAMING_DEFAULT);
        return switch (mode)
        {
            case THREAD_NAMING_CLASSIC -> classicName;
            case THREAD_NAMING_NEW -> newName;
            default -> throw new IllegalArgumentException("Unknown thread naming mode: " + mode);
        };
    }

    /**
     * Event Buffer length system property name. If not set then output will default to {@link System#out}.
     */
    public static final String EVENT_LOG_FILENAME_PROP_NAME = "aeron.event.log.filename";
    /**
     * Event Buffer log file max length system property. If not set then {@link Long#MAX_VALUE} will be used.
     */
    public static final String EVENT_LOG_FILE_MAX_LENGTH = "aeron.event.log.file.max.length";

    /**
     * System property to toggle whether {@link BinaryRenderer} implementations render the remaining bytes
     * of fields that are not part of the header information.
     */
    public static final String EVENT_LOG_RENDER_DATA_PROP_NAME = "aeron.event.log.render.data";

View on GitHub (pinned to 6d60124e15)