apache/dolphinscheduler · error · ServiceException

10177

10177

Error message

worker address {0} invalid

What it means

Thrown by checkWorkerGroupAddrList when saving a worker group whose comma-separated address list contains an address that is not currently registered as a live WORKER node in the registry (ZooKeeper). The service validates each addr against registryClient.getServerMaps(RegistryNodeType.WORKER).

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/WorkerGroupServiceImpl.java:200

        // check if the worker group has any dependent environments
        List<EnvironmentWorkerGroupRelation> environmentWorkerGroupRelations =
                environmentWorkerGroupRelationMapper.selectList(new QueryWrapper<EnvironmentWorkerGroupRelation>()
                        .lambda().eq(EnvironmentWorkerGroupRelation::getWorkerGroup, workerGroup.getName()));

        if (CollectionUtils.isNotEmpty(environmentWorkerGroupRelations)) {
            throw new ServiceException(Status.WORKER_GROUP_DEPENDENT_ENVIRONMENT_EXISTS,
                    environmentWorkerGroupRelations.size());
        }
    }

    private void checkWorkerGroupAddrList(String workerGroupAddress) {
        if (Strings.isNullOrEmpty(workerGroupAddress)) {
            return;
        }
        Map<String, String> serverMaps = registryClient.getServerMaps(RegistryNodeType.WORKER);
        for (String addr : workerGroupAddress.split(Constants.COMMA)) {
            if (!serverMaps.containsKey(addr)) {
                throw new ServiceException(Status.WORKER_ADDRESS_INVALID);
            }
        }
    }

    /**
     * query worker group paging
     *
     * @param loginUser login user
     * @param pageNo    page number
     * @param searchVal search value
     * @param pageSize  page size
     * @return worker group list page
     */
    @Override
    public Result queryAllGroupPaging(User loginUser, Integer pageNo, Integer pageSize, String searchVal) {
        // list from index
        int fromIndex = (pageNo - 1) * pageSize;
        // list to index

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Verify the worker host:port matches an active entry shown in the Monitor > Service Management worker list and correct the address.
  2. Start/restart the worker process on the given host so it registers in the registry, then save.
  3. Remove dead or unregistered addresses from the worker group's address list.

Example fix

// before
setWorkerAddresses("10.0.0.5:1234,10.0.0.6:1235"); // second worker not running
// after
setWorkerAddresses("10.0.0.5:1234,10.0.0.6:1234"); // both registered, correct port
Defensive patterns

Strategy: validation

Validate before calling

Set<String> live = registryClient.getServerMaps(RegistryNodeType.WORKER).keySet();
boolean valid = Arrays.stream(addresses.split(","))
    .map(String::trim).allMatch(live::contains);

Try / catch

try {
    workerGroupService.saveWorkerGroup(loginUser, name, addrList);
} catch (ServiceException e) {
    if (e.getCode() == 10177) { /* resolve/refresh worker addresses */ }
    else throw e;
}

Prevention

When it happens

Trigger: Calling saveWorkerGroup (create/update) with workerAddresses like '192.168.1.10:1234,host:1234' where any entry is not a key of the registry's current WORKER server map.

Common situations: Typo in host or port; worker process is down so it is absent from the registry; stale worker address from a decommissioned node; saving via API without quotes so whitespace makes the key mismatch.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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