What causes "Status.QUERY_ENVIRONMENT_BY_NAME_ERROR" in apache/dolphinscheduler?

List available environments (GET /dolphinscheduler/environments/list) and correct the name in the caller.

apache/dolphinscheduler · error · ServiceException

QUERY_ENVIRONMENT_BY_NAME_ERROR

QUERY_ENVIRONMENT_BY_NAME_ERROR

Error message

Status.QUERY_ENVIRONMENT_BY_NAME_ERROR

What it means

Thrown by EnvironmentServiceImpl.queryEnvironmentByName when no environment with the given name exists (environmentMapper.queryByEnvironmentName returns null). This is the name-based lookup variant of the environment-not-found error; the message includes the requested name.

Source

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

                .map(EnvironmentWorkerGroupRelation::getWorkerGroup)
                .collect(Collectors.toList());

        EnvironmentDto dto = new EnvironmentDto();
        BeanUtils.copyProperties(env, dto);
        dto.setWorkerGroups(workerGroups);
        return dto;
    }

    /**
     * query environment
     *
     * @param name environment name
     */
    @Override
    public EnvironmentDto queryEnvironmentByName(String name) {
        Environment env = environmentMapper.queryByEnvironmentName(name);
        if (env == null) {
            throw new ServiceException(Status.QUERY_ENVIRONMENT_BY_NAME_ERROR, name);
        }
        List<String> workerGroups = relationMapper.queryByEnvironmentCode(env.getCode()).stream()
                .map(EnvironmentWorkerGroupRelation::getWorkerGroup)
                .collect(Collectors.toList());

        EnvironmentDto dto = new EnvironmentDto();
        BeanUtils.copyProperties(env, dto);
        dto.setWorkerGroups(workerGroups);
        return dto;
    }

    /**
     * delete environment
     *
     * @param loginUser login user
     * @param code environment code
     */
    @Transactional

View on GitHub (pinned to 02eac45a1b)

Solutions

List available environments (GET /dolphinscheduler/environments/list) and correct the name in the caller.
Recreate the environment with the expected name.
Resolve names dynamically (by listing) instead of hardcoding them in scripts.

Example fix

// before
EnvironmentDto env = environmentService.queryEnvironmentByName("prod-env");
// after
List<EnvironmentDto> envs = environmentService.queryEnvironmentList();
EnvironmentDto env = envs.stream()
        .filter(e -> e.getName().equalsIgnoreCase("prod-env"))
        .findFirst()
        .orElseThrow(() -> new IllegalStateException("Available: " + envs.stream().map(EnvironmentDto::getName).collect(Collectors.toList())));

Defensive patterns

Strategy: try-catch

Validate before calling

public boolean environmentNameExists(String name) {
    try {
        environmentService.queryEnvironmentByName(name);
        return true;
    } catch (ServiceException e) {
        return false;
    }
}

Try / catch

try {
    EnvironmentDto env = environmentService.queryEnvironmentByName(name);
} catch (ServiceException e) {
    if (String.valueOf(e.getMessage()).contains("QUERY_ENVIRONMENT_BY_NAME_ERROR")) {
        // list environments and either fix the name or create the environment
    }
}

Prevention

List environments at pipeline start instead of hardcoding names
Match name casing exactly (lookups are case-sensitive)
Alert on environment deletion events if other systems depend on the name

When it happens

Trigger: GET /dolphinscheduler/environments/by-name/{name} (or service queryEnvironmentByName) with a name that was never registered, was renamed, or was deleted; scripts using a hard-coded environment name after someone renamed the environment in the UI.

Common situations: Deployment pipelines pinned to environment names that differ between dev/prod clusters; environments deleted as part of cleanup while tasks still reference them; case-sensitivity mismatches ('Default' vs 'default').

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

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