apache/dolphinscheduler · error · RegistryException

put key:%s, value:%s error

Error message

put key:%s, value:%s error

What it means

Wrapper thrown in JdbcRegistry.put: any exception raised while writing the key/value pair (as EPHEMERAL or PERSISTENT data) to the registry database — SQL errors, constraint violations, connectivity loss — is rethrown as a RegistryException carrying the key and value plus the original cause.

Source

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

            Optional<JdbcRegistryDataDTO> jdbcRegistryDataOptional = jdbcRegistryClient.getJdbcRegistryDataByKey(key);
            if (!jdbcRegistryDataOptional.isPresent()) {
                throw new RegistryException("key: " + key + " not exist");
            }
            return jdbcRegistryDataOptional.get().getDataValue();
        } catch (RegistryException registryException) {
            throw registryException;
        } catch (Exception e) {
            throw new RegistryException(String.format("Get key: %s error", key), e);
        }
    }

    @Override
    public void put(String key, String value, boolean deleteOnDisconnect) {
        try {
            DataType dataType = deleteOnDisconnect ? DataType.EPHEMERAL : DataType.PERSISTENT;
            jdbcRegistryClient.putJdbcRegistryData(key, value, dataType);
        } catch (Exception ex) {
            throw new RegistryException(String.format("put key:%s, value:%s error", key, value), ex);
        }
    }

    @Override
    public void delete(String key) {
        try {
            jdbcRegistryClient.deleteJdbcRegistryDataByKey(key);
        } catch (Exception e) {
            throw new RegistryException(String.format("Delete key: %s error", key), e);
        }
    }

    @Override
    public Collection<String> children(String key) {
        try {
            final List<JdbcRegistryDataDTO> children = jdbcRegistryClient.listJdbcRegistryDataChildren(key);
            return children
                    .stream()

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Check the cause exception for the underlying SQL error
  2. Verify DB connectivity and that the registry tables exist
  3. Retry the put with backoff for transient connection failures
  4. Check for concurrent writers on the same key; use acquireLock to serialize
Defensive patterns

Strategy: retry

Validate before calling

if (value == null || key == null) throw new IllegalArgumentException("key/value required");

Try / catch

try { registry.put(key, value, deleteOnDisconnect); } catch (RegistryException e) { retryWithBackoff(key, value); }

Prevention

When it happens

Trigger: Calling registry.put(key, value, deleteOnDisconnect) while the DB write fails: connection lost, constraint violation, transaction error, oversized value, or lock contention on the key row.

Common situations: Metadata DB restarted or unreachable; duplicate-key conflicts when two nodes put the same path concurrently; value exceeding column length.

Related errors

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