OtterMind/Chat2DB · error · CliDomainException

datasource_connection_failed

datasource_connection_failed

Error message

datasource_connection_failed

What it means

A CliDomainException with code datasource_connection_failed, thrown during CliDataSourceServiceImpl.create after preConnectForCreate returns canConnect != TRUE. The detail map carries the underlying connection test's errorCode, errorDetail, and durationMs, and the message falls back to the test's errorMessage. The create is aborted before any datasource record is persisted.

Source

Thrown at chat2db-community-server/chat2db-community-domain/chat2db-community-domain-core/src/main/java/ai/chat2db/community/domain/core/impl/cli/CliDataSourceServiceImpl.java:105

            response.setCanConnect(Boolean.TRUE);
        } catch (Exception exception) {
            response.setCanConnect(Boolean.FALSE);
            response.setErrorCode("datasource_connection_failed");
            response.setErrorMessage(exception.getMessage());
        } finally {
            response.setDurationMs(System.currentTimeMillis() - startedAt);
        }
        return response;
    }

    @Override
    public CliDataSource create(CliDataSourceCreateRequest request) {
        validateCreateRequest(request);
        normalizeCreateDbType(request);
        normalizeCreateRequest(request);
        CliConnectionTestResponse connectionTest = preConnectForCreate(request);
        if (!Boolean.TRUE.equals(connectionTest.getCanConnect())) {
            throw new CliDomainException("datasource_connection_failed",
                    firstNonBlank(connectionTest.getErrorMessage(), "Datasource connection test failed."),
                    Map.of(
                            "errorCode", StringUtils.defaultString(connectionTest.getErrorCode()),
                            "errorDetail", StringUtils.defaultString(connectionTest.getErrorDetail()),
                            "durationMs", connectionTest.getDurationMs() == null ? 0L : connectionTest.getDurationMs()
                    ));
        }
        WorkspaceDataSource dataSource = cliDataSourceConverter.create2storage(request);
        validateCreate(dataSource);
        if (dataSource.getDriverConfig() == null || StringUtils.isBlank(dataSource.getDriverConfig().getJdbcDriverClass())) {
            dataSource.setDriverConfig(dataSourceService.defaultDriverConfig(dataSource.getType()));
        }
        Long dataSourceId = workspaceStorageFacade.createDataSource(dataSource);
        CliDataSource response = get(dataSourceId);
        enrichCreateResponse(response, request);
        return response;
    }

View on GitHub (pinned to 5ee1e990e7)

Solutions

  1. Read the returned details.errorCode/errorDetail (and the message) to identify the underlying JDBC failure.
  2. Verify host, port, database, user, password are correct for the target DB.
  3. Confirm network reachability and firewall rules between the Chat2DB host and the DB.
  4. Ensure the correct JDBC driver is configured (driverConfig) for the dbType; test the same URL with a plain JDBC client.
  5. If SSH is required, provide the ssh config block in the create request.

Example fix

// before: pre-connect fails on wrong port
create({ dbType: 'MYSQL', host: 'db', port: '3307', database: 'app', user: 'u', password: 'p' })

// after
create({ dbType: 'MYSQL', host: 'db', port: '3306', database: 'app', user: 'u', password: 'p' })
Defensive patterns

Strategy: try-catch

Validate before calling

CliConnectionTestResponse probe = cliDataSourceService.testConnection(toTestRequest(createReq));
if (!Boolean.TRUE.equals(probe.getCanConnect())) {
    // surface probe.getErrorMessage()/getErrorCode() to the user, do NOT call create
    return failedBeforeCreate(probe);
}

Try / catch

try {
    return cliDataSourceService.create(request);
} catch (CliDomainException e) {
    if ("datasource_connection_failed".equals(e.getCode())) {
        Map<String,Object> d = e.getDetails();
        return connectionFailureResult((String) d.get("errorCode"), (String) d.get("errorDetail"));
    }
    throw e;
}

Prevention

When it happens

Trigger: POST datasource create with host/port/url/credentials that fail the JDBC connection test: wrong host, wrong port, wrong credentials, driver not loaded, DB unreachable, or SSL/auth mismatch.

Common situations: Typo in host or port; password mismatch; DB behind a firewall not reachable from the host; unsupported/missing JDBC driver; database name does not exist; SSH tunnel required but not configured.

Related errors

AI-assisted analysis of OtterMind/Chat2DB@5ee1e990e7 (2026-08-14). Data as JSON: /api/errors/b58f332f941c8d9e. Report an issue: GitHub.