apache/dolphinscheduler · warning · ServiceException

DESCRIPTION_TOO_LONG_ERROR

DESCRIPTION_TOO_LONG_ERROR

Error message

Status.DESCRIPTION_TOO_LONG_ERROR

What it means

Thrown by EnvironmentServiceImpl.createEnvironment when the supplied environment description exceeds the configured maximum length (checkDescriptionLength returns true). DolphinScheduler limits environment descriptions to 255 characters (database column limit). The API rejects the create request before any insert occurs.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/EnvironmentServiceImpl.java:105

     *
     * @param loginUser login user
     * @param name environment name
     * @param config environment config
     * @param desc environment desc
     * @param workerGroups worker groups
     */
    @Override
    @Transactional
    public Long createEnvironment(User loginUser,
                                  String name,
                                  String config,
                                  String desc,
                                  String workerGroups) {
        if (!canOperatorPermissions(loginUser, null, AuthorizationType.ENVIRONMENT, ENVIRONMENT_CREATE)) {
            throw new ServiceException(Status.USER_NO_OPERATION_PERM);
        }
        if (checkDescriptionLength(desc)) {
            throw new ServiceException(Status.DESCRIPTION_TOO_LONG_ERROR);
        }
        checkParams(name, config, workerGroups);

        Environment environment = environmentMapper.queryByEnvironmentName(name);
        if (environment != null) {
            throw new ServiceException(Status.ENVIRONMENT_NAME_EXISTS, name);
        }

        Environment env = new Environment();
        env.setName(name);
        env.setConfig(config);
        env.setDescription(desc);
        env.setOperator(loginUser.getId());
        env.setCreateTime(new Date());
        env.setUpdateTime(new Date());
        env.setCode(CodeGenerateUtils.genCode());

        if (environmentMapper.insert(env) > 0) {

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Shorten the description parameter to 255 characters or fewer and retry the create call.
2. Truncate the description in the calling client before submitting (e.g. desc.substring(0, Math.min(desc.length(), 255))).
3. Move extended notes into external documentation and keep only a short summary in the description field.

Example fix

// before
desc = longGeneratedText; // > 255 chars
environmentService.createEnvironment(loginUser, name, config, desc, workerGroups);
// after
desc = longGeneratedText.substring(0, Math.min(longGeneratedText.length(), 255));
environmentService.createEnvironment(loginUser, name, config, desc, workerGroups);

public static void assertDescriptionLength(String desc) {
    if (desc != null && desc.length() > 255) {
        throw new IllegalArgumentException("Environment description exceeds 255 chars: " + desc.length());
    }
}

public static boolean isDescriptionValid(String desc) {
    return desc == null || desc.length() <= 255;
}

try {
    environmentService.createEnvironment(loginUser, name, config, desc, workerGroups);
} catch (ServiceException e) {
    if (String.valueOf(e.getMessage()).contains("DESCRIPTION_TOO_LONG")) {
        desc = desc.substring(0, 255);
        // retry once
    }
}

When it happens

Trigger: POST /dolphinscheduler/environments with a 'description' form parameter longer than 255 characters; UI clients pasting long prose into the description field; scripts programmatically generating descriptions that exceed the limit.

Common situations: Automation tools writing generated configuration notes into the description field; users copying documentation text into the description box; clients not validating length client-side before submitting.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• ENVIRONMENT_NAME_IS_NULL
• ENVIRONMENT_NAME_EXISTS
• CREATE_ENVIRONMENT_ERROR
• QUERY_ENVIRONMENT_BY_CODE_ERROR
• QUERY_ENVIRONMENT_BY_NAME_ERROR

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