{"record":{"id":"a3e418754e39a50b","repo":"apache/seatunnel","slug":"connect-database-failed-a3e418","errorCode":"CONNECT_DATABASE_FAILED","errorMessage":"unable to open JDBC writer","messagePattern":"unable to open JDBC writer","errorType":"error_code","errorClass":"JdbcConnectorException","httpStatus":null,"severity":"critical","filePath":"seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/JdbcOutputFormat.java","lineNumber":76,"sourceCode":"    private transient volatile Exception flushException;\n    private transient long lastFlushTimeMs;\n    private transient boolean failFastOnRowLevelSqlState;\n\n    public JdbcOutputFormat(\n            JdbcConnectionProvider connectionProvider,\n            JdbcConnectionConfig jdbcConnectionConfig,\n            StatementExecutorFactory<E> statementExecutorFactory) {\n        this.connectionProvider = checkNotNull(connectionProvider);\n        this.jdbcConnectionConfig = checkNotNull(jdbcConnectionConfig);\n        this.statementExecutorFactory = checkNotNull(statementExecutorFactory);\n    }\n\n    /** Connects to the target database and initializes the prepared statement. */\n    public void open() throws IOException {\n        try {\n            connectionProvider.getOrEstablishConnection();\n        } catch (Exception e) {\n            throw new JdbcConnectorException(\n                    JdbcConnectorErrorCode.CONNECT_DATABASE_FAILED,\n                    \"unable to open JDBC writer\",\n                    e);\n        }\n        jdbcStatementExecutor = createAndOpenStatementExecutor(statementExecutorFactory);\n        lastFlushTimeMs = System.currentTimeMillis();\n    }\n\n    private E createAndOpenStatementExecutor(StatementExecutorFactory<E> statementExecutorFactory) {\n        E exec = statementExecutorFactory.get();\n        try {\n            exec.prepareStatements(connectionProvider.getConnection());\n        } catch (SQLException e) {\n            throw new JdbcConnectorException(\n                    CommonErrorCodeDeprecated.SQL_OPERATION_FAILED,\n                    \"unable to open JDBC writer\",\n                    e);\n        }","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/JdbcOutputFormat.java#L58-L94","documentation":"JdbcOutputFormat.open obtains a connection via connectionProvider.getOrEstablishConnection(); any exception is wrapped in JdbcConnectorException CONNECT_DATABASE_FAILED with message 'unable to open JDBC writer'. This means the sink writer could not reach or authenticate to the database at task start.","triggerScenarios":"getOrEstablishConnection fails: host/port wrong or unreachable, wrong user/password, driver class missing, TLS handshake failure, database max connections reached, or URL invalid.","commonSituations":"Firewall/SG rules blocking the SeaTunnel worker, DB restarted or failover moved the host, expired credentials, forgotten driver jar in the plugin directory, connection pool exhausted by too many writer tasks.","solutions":["Read the wrapped cause for the driver-level reason (refused vs auth vs driver-missing)","Verify the url, user, password and that the database is reachable from the worker (telnet/nc host port)","Place the correct JDBC driver jar in the connector's lib/plugins directory","Check max_connections / connection limits and reduce sink parallelism if saturated","Confirm SSL/TLS settings and truststore if the DB requires encrypted connections"],"exampleFix":"// before\nurl = \"jdbc:mysql://db-prod:3307/mydb\" // wrong port; DB listens on 3306\n// after\nurl = \"jdbc:mysql://db-prod:3306/mydb\"","handlingStrategy":"retry","validationCode":"// pre-flight connectivity check from the worker host\ntry (Socket s = new Socket()) {\n    s.connect(new InetSocketAddress(host, port), 5000); // throws if unreachable\n}\nDriverManager.getConnection(url, user, pass).close();","typeGuard":null,"tryCatchPattern":"try {\n    outputFormat.open();\n} catch (JdbcConnectorException e) {\n    if (e.getErrorCode() == JdbcConnectorErrorCode.CONNECT_DATABASE_FAILED) {\n        retryWithBackoff(() -> outputFormat.open());\n    } else {\n        throw e;\n    }\n}","preventionTips":["Open firewall/security-group rules from workers to the DB port","Keep the JDBC driver jar in the connector lib directory","Rotate credentials before expiry and update secrets","Monitor max_connections; size sink parallelism accordingly"],"tags":["jdbc","connection","sink"],"backgroundTag":"connection-refused","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}