{"record":{"id":"0ab6ad87fbc1b4b1","repo":"t8y2/dbx","slug":"statement-n-failed-cause-message","errorCode":null,"errorMessage":"Statement N failed: <cause message>","messagePattern":"Statement N failed: <cause message>","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"agents/common/src/main/java/com/dbx/agent/BatchExecutor.java","lineNumber":63,"sourceCode":"    }\n\n    private static Long tryExecuteBatch(Connection conn, List<String> statements) throws Exception {\n        try (Statement stmt = conn.createStatement()) {\n            try {\n                int statementCount = 0;\n                for (String statement : statements) {\n                    String trimmed = JdbcExecutor.trimSql(statement);\n                    if (trimmed.isEmpty()) {\n                        continue;\n                    }\n                    stmt.addBatch(trimmed);\n                    statementCount++;\n                }\n                return statementCount == 0 ? 0L : affectedRows(executeBatch(stmt));\n            } catch (BatchUpdateException e) {\n                long[] counts = e.getLargeUpdateCounts();\n                int failedIndex = counts == null ? 1 : counts.length + 1;\n                throw new RuntimeException(\"Statement \" + failedIndex + \" failed: \" + e.getMessage(), e);\n            } catch (SQLFeatureNotSupportedException | UnsupportedOperationException | AbstractMethodError e) {\n                return null;\n            }\n        }\n    }\n\n    private static long executeIndividually(Connection conn, List<String> statements) throws Exception {\n        long totalAffected = 0;\n        int statementIndex = 0;\n        try (Statement stmt = conn.createStatement()) {\n            for (String statement : statements) {\n                String trimmed = JdbcExecutor.trimSql(statement);\n                if (trimmed.isEmpty()) {\n                    continue;\n                }\n                statementIndex++;\n                try {\n                    if (!stmt.execute(trimmed)) {","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/common/src/main/java/com/dbx/agent/BatchExecutor.java#L45-L81","documentation":"When JDBC's executeBatch fails with a BatchUpdateException, tryExecuteBatch wraps it in a RuntimeException naming the statement index that failed (derived from the large update counts) and the driver's cause message. The original exception is preserved as the cause.","triggerScenarios":"A batch statement fails at execution time: constraint violation, syntax error, type mismatch, or dead row in one of the batched statements; driver returns partial update counts.","commonSituations":"Bad data in one row of a bulk insert; duplicate key in batched upserts; SQL dialect mismatch on one statement; connection dropped mid-batch.","solutions":["Read the cause (getCause) and failed statement index from the message, fix the offending statement/data","Validate batch inputs (uniqueness, types) before executing","Split large batches to isolate failures and resubmit remaining statements","Check driver support for large update counts (counts null implies index fallback)","Enable rewrite-batch options compatible with your driver"],"exampleFix":"// before\nstmt.addBatch(\"INSERT INTO t VALUES (?)\"); // row 5 duplicates a key\nlong n = BatchExecutor.batchAffected(stmt); // RuntimeException: Statement 6 failed\n// after\ntry {\n    long n = BatchExecutor.batchAffected(stmt);\n} catch (RuntimeException e) {\n    int failedStmt = parseFailedIndex(e.getMessage());\n    dedupeRow(batch, failedStmt - 1);\n    resubmitRemaining(stmt, failedStmt);\n}","handlingStrategy":"try-catch","validationCode":"// pre-validate batch rows\nSet<Key> seen = new HashSet<>();\nfor (Row r : rows) {\n    if (!seen.add(r.key())) throw new IllegalArgumentException(\"duplicate key \" + r.key());\n}","typeGuard":null,"tryCatchPattern":"try {\n    long n = BatchExecutor.batchAffected(stmt);\n} catch (RuntimeException e) {\n    if (e.getCause() instanceof BatchUpdateException) {\n        int failedIdx = parseIndex(e.getMessage()); // 'Statement N failed'\n        BatchUpdateException bue = (BatchUpdateException) e.getCause();\n        // inspect bue.getLargeUpdateCounts() and recover/resubmit from failedIdx\n    }\n}","preventionTips":["Validate data (types, uniqueness, nullability) before batching","Keep the cause chain: always inspect getCause() for the driver-level error","Split very large batches to limit blast radius of a single bad statement","Check for connection-drop errors which can also surface as BatchUpdateException"],"tags":["jdbc","batch","sql-execution","runtime-exception"],"backgroundTag":"batch-update-failed","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}