What causes "time zone [{0}] is illegal" in apache/dolphinscheduler?

Use a valid IANA time zone ID such as 'Asia/Shanghai' or 'America/New_York'

apache/dolphinscheduler · error · ServiceException

130031

130031

Error message

time zone [{0}] is illegal

What it means

Thrown by UsersServiceImpl.updateUser when the timeZone parameter is non-empty but CheckUtils.checkTimeZone cannot resolve it to a valid Java time zone ID. The update aborts with TIME_ZONE_ILLEGAL (code 130031) and the offending value is reported in the message.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/UsersServiceImpl.java:396

        if (StringUtils.isNotEmpty(email)) {
            if (!CheckUtils.checkEmail(email)) {
                throw new ServiceException(Status.REQUEST_PARAMS_NOT_VALID_ERROR, email);
            }
            user.setEmail(email);
        }

        if (StringUtils.isNotEmpty(phone) && !CheckUtils.checkPhone(phone)) {
            throw new ServiceException(Status.REQUEST_PARAMS_NOT_VALID_ERROR, phone);
        }

        if (state == 0 && user.getState() != state && Objects.equals(loginUser.getId(), user.getId())) {
            throw new ServiceException(Status.NOT_ALLOW_TO_DISABLE_OWN_ACCOUNT);
        }

        if (StringUtils.isNotEmpty(timeZone)) {
            if (!CheckUtils.checkTimeZone(timeZone)) {
                throw new ServiceException(Status.TIME_ZONE_ILLEGAL, timeZone);
            }
            user.setTimeZone(timeZone);
        }

        user.setPhone(phone);
        user.setQueue(queue);
        user.setState(state);
        user.setUpdateTime(new Date());
        user.setTenantId(tenantId);
        // updateWorkflowInstance user
        if (!userDao.updateById(user)) {
            throw new ServiceException(Status.UPDATE_USER_ERROR);
        }
        return user;
    }

    /**
     * delete user

View on GitHub (pinned to 02eac45a1b)

Solutions

Use a valid IANA time zone ID such as 'Asia/Shanghai' or 'America/New_York'
Verify with java.util.TimeZone.getTimeZone(value) and check it is not GMT fallback
Pass empty string/omit the parameter to leave the time zone unchanged

Example fix

// before
updateUser(..., timeZone="UTC+8", ...);
// after
updateUser(..., timeZone="Asia/Shanghai", ...);

Defensive patterns

Strategy: validation

Validate before calling

if (timeZone != null && !timeZone.isEmpty()
        && java.util.TimeZone.getTimeZone(timeZone).getID().equals("GMT") && !timeZone.equals("GMT")) {
    throw new IllegalArgumentException("illegal time zone: " + timeZone);
}

Try / catch

try { userService.updateUser(...); } catch (ServiceException e) { if (e.getCode() == 130031) { showFieldError("timeZone", "Use IANA zone IDs like Asia/Shanghai"); } }

Prevention

Use a timezone picker listing IANA IDs only
Validate with TimeZone.getTimeZone and check the resolved ID
Avoid GMT-offset strings and abbreviations

When it happens

Trigger: Calling users/update with timeZone values like 'UTC+8', 'CST', 'gmt', or a misspelled zone; only non-empty values are validated, so empty string skips the check.

Common situations: Frontend sending GMT offsets instead of IANA zone IDs; users typing abbreviations ('PST') rather than 'America/Los_Angeles'; locale differences after upgrades changing accepted formats.

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

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