apache/dolphinscheduler · error · IllegalArgumentException

Cannot find the task instance log base path, please check yo

Error message

Cannot find the task instance log base path, please check your logback.xml file

What it means

LogUtils.getTaskInstanceLogFullPath() reads TASK_INSTANCE_LOG_BASE_PATH, which is populated from the logback.xml appender path. If it is null, the logback.xml on the worker does not define the expected task-instance log base path, so an IllegalArgumentException is thrown instead of returning a bogus path.

Source

Thrown at dolphinscheduler-task-plugin/dolphinscheduler-task-api/src/main/java/org/apache/dolphinscheduler/plugin/task/api/utils/LogUtils.java:115

    /**
     * todo: Remove the submitTime parameter?
     * The task instance log full path, the path is like:{log.base}/{taskSubmitTime}/{workflowDefinitionCode}/{workflowDefinitionVersion}/{}workflowInstance}/{taskInstance}.log
     *
     * @param taskFirstSubmitTime       task first submit time
     * @param workflowDefinitionCode    workflow definition code
     * @param workflowDefinitionVersion workflow definition version
     * @param workflowInstanceId        workflow instance id
     * @param taskInstanceId            task instance id.
     * @return task instance log full path.
     */
    public static String getTaskInstanceLogFullPath(Date taskFirstSubmitTime,
                                                    Long workflowDefinitionCode,
                                                    int workflowDefinitionVersion,
                                                    int workflowInstanceId,
                                                    int taskInstanceId) {
        if (TASK_INSTANCE_LOG_BASE_PATH == null) {
            throw new IllegalArgumentException(
                    "Cannot find the task instance log base path, please check your logback.xml file");
        }
        final String taskLogFileName = Paths.get(
                String.valueOf(workflowDefinitionCode),
                String.valueOf(workflowDefinitionVersion),
                String.valueOf(workflowInstanceId),
                String.format("%s.log", taskInstanceId)).toString();
        return TASK_INSTANCE_LOG_BASE_PATH
                .resolve(DateUtils.format(taskFirstSubmitTime, DateConstants.YYYYMMDD, null))
                .resolve(taskLogFileName)
                .toString();
    }

    /**
     * Get task instance log base absolute path, this is defined in logback.xml
     *
     * @return
     */

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Restore/merge the stock logback.xml from the matching distribution version onto each worker.
2. Ensure the task log appender and its <file>/<fileNamePattern> path are defined exactly as the version expects.
3. Restart workers after fixing logback.xml so the static base path is re-read.
4. Verify with a small deployment that task logs appear under the expected base path directory.

Example fix

// before (logback.xml)
<appender name="TASKLOGFILE" class="..."> <!-- removed path -->
// after (logback.xml)
<appender name="TASKLOGFILE" class="org.apache.dolphinscheduler.plugin.task.api.log.TaskLogAppender">
  <file>${log.base}/task-instance/</file>
  ...
</appender>

// startup check on worker
if (LogUtils.getTaskInstanceLogFullPath(new Date(), 0L, 1, 1, 1) == null) {
    throw new IllegalStateException("logback.xml task log base path not configured");
}

try {
    path = LogUtils.getTaskInstanceLogFullPath(submitTime, code, ver, wfId, taskId);
} catch (IllegalArgumentException e) {
    log.error("worker logback.xml missing task log appender", e);
    throw e;
}

When it happens

Trigger: Calling getTaskInstanceLogFullPath(...) on a worker whose logback.xml lacks the task log appender (or uses a modified appender whose file path no longer matches what LogUtils parses), so the static TASK_INSTANCE_LOG_BASE_PATH is never set.

Common situations: Custom/overwritten logback.xml deployed to workers; upgrading DolphinScheduler with an old logback.xml; mixing server and worker distributions; manually editing logback.xml and renaming the TASK_LOG_FILE appender's path property.

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

• remote.logging.google.cloud.storage.bucket.name is blank
• remote.logging.oss.bucket.name is empty
• remote.logging.s3.bucket.name is blank
• receivers must not be null
• url can not be null

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/00c613f5d1d4053b. Report an issue: GitHub.