What causes "Check key: %s exist error" in apache/dolphinscheduler?

Inspect the cause for the real connection/SQL error

apache/dolphinscheduler · error · RegistryException

Check key: %s exist error

Error message

Check key: %s exist error

What it means

Thrown by JdbcRegistry.exists when the existence check query against the registry database fails. Unlike get, absence of the key returns false rather than throwing — this error means the check itself could not run.

Source

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

        try {
            final List<JdbcRegistryDataDTO> children = jdbcRegistryClient.listJdbcRegistryDataChildren(key);
            return children
                    .stream()
                    .map(JdbcRegistryDataDTO::getDataKey)
                    .map(fullPath -> StringUtils.substringBefore(fullPath.substring(key.length() + 1), "/"))
                    .distinct()
                    .collect(Collectors.toList());
        } catch (Exception e) {
            throw new RegistryException(String.format("Get key: %s children error", key), e);
        }
    }

    @Override
    public boolean exists(String key) {
        try {
            return jdbcRegistryClient.existJdbcRegistryDataKey(key);
        } catch (Exception e) {
            throw new RegistryException(String.format("Check key: %s exist error", key), e);
        }
    }

    @Override
    public boolean acquireLock(String key) {
        try {
            jdbcRegistryClient.acquireJdbcRegistryLock(key);
            return true;
        } catch (RegistryException e) {
            throw e;
        } catch (Exception e) {
            throw new RegistryException(String.format("Acquire lock: %s error", key), e);
        }
    }

    @Override
    public boolean acquireLock(String key, long timeout) {
        try {

View on GitHub (pinned to 02eac45a1b)

Solutions

Inspect the cause for the real connection/SQL error
Verify DB connectivity and registry configuration
Retry with backoff for transient failures
Confirm registry tables exist in the configured schema

Defensive patterns

Strategy: retry

Validate before calling

// check datasource: try (Connection c = dataSource.getConnection()) { }

Try / catch

try { exists = registry.exists(key); } catch (RegistryException e) { exists = false; /* or fail fast per business need */ }

Prevention

Confirm schema/tables exist before first use
Use exists() for absence checks so absence never throws
Set up DB health checks and retries

When it happens

Trigger: Calling registry.exists(key) while the DB is unreachable, credentials are wrong, or the query throws.

Common situations: Metadata DB down or during failover, wrong JDBC datasource config, schema not initialized.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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