{"record":{"id":"b58f332f941c8d9e","repo":"OtterMind/Chat2DB","slug":"datasource-connection-failed","errorCode":"datasource_connection_failed","errorMessage":"datasource_connection_failed","messagePattern":"datasource_connection_failed","errorType":"error_code","errorClass":"CliDomainException","httpStatus":null,"severity":"error","filePath":"chat2db-community-server/chat2db-community-domain/chat2db-community-domain-core/src/main/java/ai/chat2db/community/domain/core/impl/cli/CliDataSourceServiceImpl.java","lineNumber":105,"sourceCode":"            response.setCanConnect(Boolean.TRUE);\n        } catch (Exception exception) {\n            response.setCanConnect(Boolean.FALSE);\n            response.setErrorCode(\"datasource_connection_failed\");\n            response.setErrorMessage(exception.getMessage());\n        } finally {\n            response.setDurationMs(System.currentTimeMillis() - startedAt);\n        }\n        return response;\n    }\n\n    @Override\n    public CliDataSource create(CliDataSourceCreateRequest request) {\n        validateCreateRequest(request);\n        normalizeCreateDbType(request);\n        normalizeCreateRequest(request);\n        CliConnectionTestResponse connectionTest = preConnectForCreate(request);\n        if (!Boolean.TRUE.equals(connectionTest.getCanConnect())) {\n            throw new CliDomainException(\"datasource_connection_failed\",\n                    firstNonBlank(connectionTest.getErrorMessage(), \"Datasource connection test failed.\"),\n                    Map.of(\n                            \"errorCode\", StringUtils.defaultString(connectionTest.getErrorCode()),\n                            \"errorDetail\", StringUtils.defaultString(connectionTest.getErrorDetail()),\n                            \"durationMs\", connectionTest.getDurationMs() == null ? 0L : connectionTest.getDurationMs()\n                    ));\n        }\n        WorkspaceDataSource dataSource = cliDataSourceConverter.create2storage(request);\n        validateCreate(dataSource);\n        if (dataSource.getDriverConfig() == null || StringUtils.isBlank(dataSource.getDriverConfig().getJdbcDriverClass())) {\n            dataSource.setDriverConfig(dataSourceService.defaultDriverConfig(dataSource.getType()));\n        }\n        Long dataSourceId = workspaceStorageFacade.createDataSource(dataSource);\n        CliDataSource response = get(dataSourceId);\n        enrichCreateResponse(response, request);\n        return response;\n    }\n","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/OtterMind/Chat2DB/blob/5ee1e990e73fbcae1969dc554be254fedb3ab888/chat2db-community-server/chat2db-community-domain/chat2db-community-domain-core/src/main/java/ai/chat2db/community/domain/core/impl/cli/CliDataSourceServiceImpl.java#L87-L123","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the returned details.errorCode/errorDetail (and the message) to identify the underlying JDBC failure.","Verify host, port, database, user, password are correct for the target DB.","Confirm network reachability and firewall rules between the Chat2DB host and the DB.","Ensure the correct JDBC driver is configured (driverConfig) for the dbType; test the same URL with a plain JDBC client.","If SSH is required, provide the ssh config block in the create request."],"exampleFix":"// before: pre-connect fails on wrong port\ncreate({ dbType: 'MYSQL', host: 'db', port: '3307', database: 'app', user: 'u', password: 'p' })\n\n// after\ncreate({ dbType: 'MYSQL', host: 'db', port: '3306', database: 'app', user: 'u', password: 'p' })","handlingStrategy":"try-catch","validationCode":"CliConnectionTestResponse probe = cliDataSourceService.testConnection(toTestRequest(createReq));\nif (!Boolean.TRUE.equals(probe.getCanConnect())) {\n    // surface probe.getErrorMessage()/getErrorCode() to the user, do NOT call create\n    return failedBeforeCreate(probe);\n}","typeGuard":null,"tryCatchPattern":"try {\n    return cliDataSourceService.create(request);\n} catch (CliDomainException e) {\n    if (\"datasource_connection_failed\".equals(e.getCode())) {\n        Map<String,Object> d = e.getDetails();\n        return connectionFailureResult((String) d.get(\"errorCode\"), (String) d.get(\"errorDetail\"));\n    }\n    throw e;\n}","preventionTips":["Run a connection test before create to validate credentials and reachability.","Verify network/firewall access to the DB host:port from the Chat2DB host.","Confirm the JDBC driver for the dbType is available and correct.","Store credentials in a secret manager rather than hardcoding, to avoid typos."],"tags":["datasource","jdbc","connection","cli"],"backgroundTag":null,"analyzedSha":"5ee1e990e73fbcae1969dc554be254fedb3ab888","analyzedAt":"2026-08-14T07:05:03.077Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}