apache/dolphinscheduler · error · ServiceException

QUERY_ENVIRONMENT_BY_CODE_ERROR

QUERY_ENVIRONMENT_BY_CODE_ERROR

Error message

Status.QUERY_ENVIRONMENT_BY_CODE_ERROR

What it means

Thrown by EnvironmentServiceImpl.queryEnvironmentByCode when no environment row matches the given code (environmentMapper.queryByEnvironmentCode returns null). Environment codes are snowflake-style generated Longs; querying a code that was never created — or was deleted — produces this error.

Source

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

        return environmentList.stream().map(environment -> {
            EnvironmentDto dto = new EnvironmentDto();
            BeanUtils.copyProperties(environment, dto);
            dto.setWorkerGroups(relationMap.getOrDefault(environment.getCode(), new ArrayList<>()));
            return dto;
        }).collect(Collectors.toList());
    }

    /**
     * query environment
     *
     * @param code environment code
     */
    @Override
    public EnvironmentDto queryEnvironmentByCode(Long code) {
        Environment env = environmentMapper.queryByEnvironmentCode(code);
        if (env == null) {
            throw new ServiceException(Status.QUERY_ENVIRONMENT_BY_CODE_ERROR, code);
        }
        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;
    }

    /**
     * query environment
     *
     * @param name environment name
     */
    @Override
    public EnvironmentDto queryEnvironmentByName(String name) {

View on GitHub (pinned to 02eac45a1b)

Solutions

1. List all environments (GET /dolphinscheduler/environments/list) and use the correct code.
2. Recreate the missing environment and update task definitions to reference the new code.
3. Fix the calling code to fetch the code dynamically rather than hardcoding it.

Example fix

// before
EnvironmentDto env = environmentService.queryEnvironmentByCode(staleCode);
// after
List<EnvironmentDto> all = environmentService.queryEnvironmentList();
EnvironmentDto env = all.stream()
        .filter(e -> e.getName().equals("default"))
        .findFirst()
        .orElseThrow(() -> new IllegalStateException("Environment 'default' not found"));

public boolean environmentCodeExists(long code) {
    try {
        environmentService.queryEnvironmentByCode(code);
        return true;
    } catch (ServiceException e) {
        return false;
    }
}

try {
    EnvironmentDto env = environmentService.queryEnvironmentByCode(code);
} catch (ServiceException e) {
    // QUERY_ENVIRONMENT_BY_CODE_ERROR: refresh from environment list or recreate
    List<EnvironmentDto> all = environmentService.queryEnvironmentList();
}

When it happens

Trigger: GET /dolphinscheduler/environments/{code} with a code that does not exist; using a stale code cached from a deleted environment; passing a task's environment code that references an environment removed by another user.

Common situations: Workflows referencing environments deleted after the task was defined; stale configuration in deployment scripts; typo or truncation of the numeric code.

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

• QUERY_ENVIRONMENT_BY_NAME_ERROR
• Can not find valid environment by name %s
• QUERY_DATASOURCE_ERROR
• DESCRIPTION_TOO_LONG_ERROR
• ENVIRONMENT_NAME_EXISTS

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