apache/seatunnel · error · IllegalArgumentException

Log file path is empty, get logRef : %s

Error message

Log file path is empty, get logRef : %s

What it means

Thrown by LogUtil.getLogPath when the resolved log reference matches neither the routing appender nor the file appender — usually because the required log path properties in log4j2 configuration resolved to empty strings. The method cannot determine the node's log directory and fails with the offending logRef in the message.

Source

Thrown at seatunnel-engine/seatunnel-engine-common/src/main/java/org/apache/seatunnel/engine/common/utils/LogUtil.java:54

        String fileAppender = "fileAppender";
        PropertiesConfiguration config = getLogConfiguration();
        // Get routingAppender log file path
        String routingLogFilePath = getRoutingLogFilePath(config);

        // Get fileAppender log file path
        String fileLogPath = getFileLogPath(config);
        String logRef =
                config.getLoggerConfig(StringUtils.EMPTY).getAppenderRefs().stream()
                        .map(Object::toString)
                        .filter(ref -> ref.contains(routingAppender) || ref.contains(fileAppender))
                        .findFirst()
                        .orElse(StringUtils.EMPTY);
        if (logRef.equals(routingAppender)) {
            return routingLogFilePath.substring(0, routingLogFilePath.lastIndexOf("/"));
        } else if (logRef.equals(fileAppender)) {
            return fileLogPath.substring(0, fileLogPath.lastIndexOf("/"));
        } else {
            throw new IllegalArgumentException(
                    String.format("Log file path is empty, get logRef : %s", logRef));
        }
    }

    private static PropertiesConfiguration getLogConfiguration() {
        LoggerContext context = (LoggerContext) LogManager.getContext(false);
        return (PropertiesConfiguration) context.getConfiguration();
    }

    private static String getRoutingLogFilePath(PropertiesConfiguration config)
            throws NoSuchFieldException, IllegalAccessException {
        Field propertiesField = BuiltConfiguration.class.getDeclaredField("appendersComponent");
        propertiesField.setAccessible(true);
        Component propertiesComponent = (Component) propertiesField.get(config);
        StrSubstitutor substitutor = config.getStrSubstitutor();
        return propertiesComponent.getComponents().stream()
                .filter(
                        component ->

View on GitHub (pinned to cf67b549a7)

Solutions

1. Ensure SEATUNNEL_HOME is set correctly and the process is started via bin/seatunnel.sh so sys properties are populated.
2. Restore the stock log4j2 configuration files (log4j2.client.properties / log4j2.properties) or re-add the routingAppender/fileAppender definitions that getLogPath expects.
3. Check that the appenders' fileName properties resolve to non-empty values (no blank placeholders in the config).

Example fix

# before (custom log4j2.properties)
appender.file.fileName =
# after
appender.file.fileName = ${sys:SEATUNNEL_HOME}/logs/seatunnel-engine-server.log

String home = System.getenv("SEATUNNEL_HOME");
if (home == null || home.isEmpty()) throw new IllegalStateException("SEATUNNEL_HOME must be set before computing log path");

try { String path = LogUtil.getLogPath("worker"); } catch (IllegalArgumentException e) { log.warn("log path unresolvable, check log4j2 config appenders", e); }

When it happens

Trigger: Calling LogUtil.getLogPath("client"|"master"|"worker") when the log4j2 config lacks the expected property (e.g. SEATUNNEL_HOME unset so ${sys:SEATUNNEL_HOME} expands empty) and no appender path matched.

Common situations: Running the client outside $SEATUNNEL_HOME so SEATUNNEL_HOME env/sys property is missing; a customized log4j2.client/log4j2.properties that renamed or removed the routing/file appenders; corrupted log config after manual edits.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

• GET {} -> HTTP {}
• Log file path is empty, no log file path configured in the c
• prepare method is not supported
• Option not be null.
• Condition operator must not be null

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/edc475e9a2f5bafa. Report an issue: GitHub.