{"record":{"id":"9d65477caa458db4","repo":"apache/dolphinscheduler","slug":"query-environment-by-name-error","errorCode":"QUERY_ENVIRONMENT_BY_NAME_ERROR","errorMessage":"Status.QUERY_ENVIRONMENT_BY_NAME_ERROR","messagePattern":"Status\\.QUERY_ENVIRONMENT_BY_NAME_ERROR","errorType":"error_code","errorClass":"ServiceException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/EnvironmentServiceImpl.java","lineNumber":260,"sourceCode":"                .map(EnvironmentWorkerGroupRelation::getWorkerGroup)\n                .collect(Collectors.toList());\n\n        EnvironmentDto dto = new EnvironmentDto();\n        BeanUtils.copyProperties(env, dto);\n        dto.setWorkerGroups(workerGroups);\n        return dto;\n    }\n\n    /**\n     * query environment\n     *\n     * @param name environment name\n     */\n    @Override\n    public EnvironmentDto queryEnvironmentByName(String name) {\n        Environment env = environmentMapper.queryByEnvironmentName(name);\n        if (env == null) {\n            throw new ServiceException(Status.QUERY_ENVIRONMENT_BY_NAME_ERROR, name);\n        }\n        List<String> workerGroups = relationMapper.queryByEnvironmentCode(env.getCode()).stream()\n                .map(EnvironmentWorkerGroupRelation::getWorkerGroup)\n                .collect(Collectors.toList());\n\n        EnvironmentDto dto = new EnvironmentDto();\n        BeanUtils.copyProperties(env, dto);\n        dto.setWorkerGroups(workerGroups);\n        return dto;\n    }\n\n    /**\n     * delete environment\n     *\n     * @param loginUser login user\n     * @param code environment code\n     */\n    @Transactional","sourceCodeStart":242,"sourceCodeEnd":278,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/EnvironmentServiceImpl.java#L242-L278","documentation":"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.","triggerScenarios":"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.","commonSituations":"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').","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."],"exampleFix":"// before\nEnvironmentDto env = environmentService.queryEnvironmentByName(\"prod-env\");\n// after\nList<EnvironmentDto> envs = environmentService.queryEnvironmentList();\nEnvironmentDto env = envs.stream()\n        .filter(e -> e.getName().equalsIgnoreCase(\"prod-env\"))\n        .findFirst()\n        .orElseThrow(() -> new IllegalStateException(\"Available: \" + envs.stream().map(EnvironmentDto::getName).collect(Collectors.toList())));","handlingStrategy":"try-catch","validationCode":"public boolean environmentNameExists(String name) {\n    try {\n        environmentService.queryEnvironmentByName(name);\n        return true;\n    } catch (ServiceException e) {\n        return false;\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    EnvironmentDto env = environmentService.queryEnvironmentByName(name);\n} catch (ServiceException e) {\n    if (String.valueOf(e.getMessage()).contains(\"QUERY_ENVIRONMENT_BY_NAME_ERROR\")) {\n        // list environments and either fix the name or create the environment\n    }\n}","preventionTips":["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"],"tags":["dolphinscheduler","not-found","environment","lookup"],"backgroundTag":"record-not-found","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}