apache/dolphinscheduler · error · IllegalArgumentException

The client is already registered:

Error message

The client is already registered:

What it means

JdbcRegistryServer.registerClient rejects registering a client whose identity (host, port and other identity fields) already exists in the server's client map. Each connected registry client must have a unique identity so heartbeats, ephemeral data ownership, and lock ownership remain unambiguous. A duplicate registration throws IllegalArgumentException.

Source

Thrown at dolphinscheduler-registry/dolphinscheduler-registry-plugins/dolphinscheduler-registry-jdbc/src/main/java/org/apache/dolphinscheduler/plugin/registry/jdbc/server/JdbcRegistryServer.java:150

    @Override
    public void registerClient(IJdbcRegistryClient jdbcRegistryClient) {
        checkNotNull(jdbcRegistryClient);

        JdbcRegistryClientIdentify jdbcRegistryClientIdentify = jdbcRegistryClient.getJdbcRegistryClientIdentify();
        checkNotNull(jdbcRegistryClientIdentify);

        JdbcRegistryClientHeartbeatDTO registryClientDTO = JdbcRegistryClientHeartbeatDTO.builder()
                .id(jdbcRegistryClientIdentify.getClientId())
                .clientName(jdbcRegistryClientIdentify.getClientName())
                .clientConfig(
                        new JdbcRegistryClientHeartbeatDTO.ClientConfig(
                                jdbcRegistryProperties.getSessionTimeout().toMillis()))
                .createTime(new Date())
                .lastHeartbeatTime(System.currentTimeMillis())
                .build();

        if (jdbcRegistryClientDTOMap.containsKey(jdbcRegistryClientIdentify)) {
            throw new IllegalArgumentException("The client is already registered: " + jdbcRegistryClientIdentify);
        }
        jdbcRegistryClientRepository.insert(registryClientDTO);
        jdbcRegistryClients.add(jdbcRegistryClient);
        jdbcRegistryClientDTOMap.put(jdbcRegistryClientIdentify, registryClientDTO);
    }

    @Override
    public void deregisterClient(IJdbcRegistryClient jdbcRegistryClient) {
        checkNotNull(jdbcRegistryClient);
        final JdbcRegistryClientIdentify clientIdentify = jdbcRegistryClient.getJdbcRegistryClientIdentify();
        checkNotNull(clientIdentify);

        jdbcRegistryClients.removeIf(client -> clientIdentify.equals(client.getJdbcRegistryClientIdentify()));
        jdbcRegistryClientDTOMap.remove(jdbcRegistryClient.getJdbcRegistryClientIdentify());

        doPurgeJdbcRegistryClientInDB(Lists.newArrayList(clientIdentify.getClientId()));
    }

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Close the existing registry client before reconnecting so the old registration is removed
  2. Make client identity unique (add PID, random UUID, or timestamp to host/port identity)
  3. Check whether the client is already connected and reuse the existing instance instead of re-registering

Example fix

// before
registryClient = new JdbcRegistryClient(identity); // identity reused after restart
registryClient.connect();
// after
if (registryClient != null) {
    registryClient.close();
}
identity = IdentityFactory.newUniqueIdentity();
registryClient = new JdbcRegistryClient(identity);
registryClient.connect();
Defensive patterns

Strategy: try-catch

Validate before calling

if (existingClient != null && existingClient.isConnected()) { return existingClient; }

Try / catch

try { server.registerClient(identity...); } catch (IllegalArgumentException e) { log.warn("Client already registered, reusing existing connection"); }

Prevention

When it happens

Trigger: Calling connect/register twice from the same process with identical identity parameters; two JVMs configured with the same host/port identity; server-side map retaining the client after an incomplete disconnect.

Common situations: Application restart logic that forgets to close the old registry client before reconnecting, cloned VMs/containers sharing identical configured identity values, retry loops that re-register without checking existing state.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

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