apache/dolphinscheduler · error · IllegalArgumentException

Can not find valid environment by name %s

Error message

Can not find valid environment by name %s

What it means

getEnvironmentInfo delegates to environmentService.queryEnvironmentByName, which throws ServiceException when no environment matches the name; the gateway converts that into IllegalArgumentException. Environments are optional-but-required-when-used config objects (worker group + env vars) referenced by name from tasks.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/python/PythonGateway.java:617

        }

        result.put("name", namedResources.get(0).getName());
        return result;
    }

    /**
     * Get environment info by given environment name. It return environment code.
     * Useful in Python API create task which need environment information.
     *
     * @param environmentName name of the environment
     */
    public Long getEnvironmentInfo(String environmentName) {
        try {
            return environmentService.queryEnvironmentByName(environmentName).getCode();
        } catch (ServiceException e) {
            String msg = String.format("Can not find valid environment by name %s", environmentName);
            log.error(msg);
            throw new IllegalArgumentException(msg);
        }
    }

    /**
     * Get resource by given resource type and full name. It return map contain resource id, name.
     * Useful in Python API create task which need workflow information.
     *
     * @param userName user who query resource
     * @param fullName full name of the resource
     * @return StorageEntity object which contains necessary information about resource
     */
    public StorageEntity queryResourcesFileInfo(String userName, String fullName) throws Exception {
        return resourceService.queryFileStatus(userName, fullName);
    }

    public String getGatewayVersion() {
        return PythonGateway.class.getPackage().getImplementationVersion();
    }

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Create the environment in the web UI (Security -> Environment Manage) with the exact name
  2. Fix the environmentName argument to match the existing environment
  3. Export/import environment configs between environments before running Python workflows
  4. Check for case/whitespace differences between the script and the stored name

Example fix

// before (Python)
task = Shell(..., environment_name="prod_env")
// after
task = Shell(..., environment_name="prod-env")  # exact name from Environment Manage
Defensive patterns

Strategy: try-catch

Validate before calling

// ensure environment exists before referencing it
boolean exists = environmentService.listEnvironments().stream()
    .anyMatch(env -> env.getName().equals(environmentName));
if (!exists) {
    throw new IllegalStateException("Environment not defined: " + environmentName);
}

Try / catch

try {
    Long code = pythonGateway.getEnvironmentInfo(environmentName);
} catch (IllegalArgumentException e) {
    log.error("Environment missing; define it in Security > Environment Manage", e);
}

Prevention

When it happens

Trigger: Calling getEnvironmentInfo(environmentName) with an environment name not defined under Security > Environment Manage.

Common situations: Python script referencing an environment configured only in another cluster; environment renamed/deleted; typo; case mismatch in environment name.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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