{"record":{"id":"9319a7c3215a8e8f","repo":"hibernate/hibernate-orm","slug":"halting-on-error-s","errorCode":null,"errorMessage":"Halting on error : %s","messagePattern":"Halting on error : (.+?)","errorType":"exception","errorClass":"SchemaManagementException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/tool/schema/internal/ExceptionHandlerHaltImpl.java","lineNumber":24,"sourceCode":"\nimport java.util.Locale;\n\nimport org.hibernate.tool.schema.spi.CommandAcceptanceException;\nimport org.hibernate.tool.schema.spi.ExceptionHandler;\nimport org.hibernate.tool.schema.spi.SchemaManagementException;\n\n/**\n * @author Steve Ebersole\n */\npublic class ExceptionHandlerHaltImpl implements ExceptionHandler {\n\t/**\n\t * Singleton access\n\t */\n\tpublic static final ExceptionHandlerHaltImpl INSTANCE = new ExceptionHandlerHaltImpl();\n\n\t@Override\n\tpublic void handleException(CommandAcceptanceException exception) {\n\t\tthrow new SchemaManagementException(\n\t\t\t\tString.format(\n\t\t\t\t\t\tLocale.ROOT,\n\t\t\t\t\t\t\"Halting on error : %s\",\n\t\t\t\t\t\texception.getMessage()\n\t\t\t\t),\n\t\t\t\texception\n\t\t);\n\t}\n}\n","sourceCodeStart":6,"sourceCodeEnd":34,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/tool/schema/internal/ExceptionHandlerHaltImpl.java#L6-L34","documentation":"The halt-on-error exception handler for schema tooling: when a DDL statement fails against a target, it is first wrapped in a CommandAcceptanceException (statement + DB error); with halting behavior active (ExceptionHandlerHaltImpl - the default unless hibernate.hbm2ddl.halt_on_error=false), Hibernate rethrows it as SchemaManagementException with 'Halting on error : <original message>'. The root cause is always one specific failing DDL command.","triggerScenarios":"Any hbm2ddl execution (create/update/drop) where a generated DDL statement fails and halting is enabled: object already exists on re-runs, dialect generating syntax the DB version rejects, insufficient DDL privileges, FK dependencies blocking drops, disk/tablespace issues - the wrapped CommandAcceptanceException message names the exact statement.","commonSituations":"Running update twice without drop ('already exists'); generated types not supported on older DB versions; CI running create on a non-clean schema; DB user lacking DDL rights; drop order violating FK constraints.","solutions":["Read the wrapped exception: the CommandAcceptanceException cause carries the failing SQL and the database's error - fix that specific statement or precondition.","Make re-runs clean: drop-first (SchemaExport.Action.DROP) or use versioned migrations instead of repeating create.","Grant the executing user the required DDL privileges.","If failures are tolerated (e.g. 'already exists' on re-run), set hibernate.hbm2ddl.halt_on_error=false so the tool logs and continues - then review the logged failures."],"exampleFix":"// before: SchemaUpdate halts at the first failing statement\nMap<String, Object> settings = new HashMap<>();\nsettings.put(\"hibernate.hbm2ddl.halt_on_error\", \"true\");\n\n// after: log failures and continue, then review them deliberately\nMap<String, Object> settings = new HashMap<>();\nsettings.put(\"hibernate.hbm2ddl.halt_on_error\", \"false\");","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    new SchemaUpdate(metadata, registry).execute(EnumSet.of(TargetType.DATABASE), ...);\n} catch (SchemaManagementException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Halting on error\")) {\n        CommandAcceptanceException cmd = (CommandAcceptanceException) e.getCause();\n        // cmd.getMessage() carries the failing DDL + DB error; handle known-benign cases (e.g. 'already exists')\n    }\n    throw e;\n}","preventionTips":["Make schema steps idempotent: drop-before-create or use versioned migrations instead of repeat create/update","Run hbm2ddl under a role with exactly the DDL privileges it needs","Set hibernate.hbm2ddl.halt_on_error=false only when logged failures are reviewed; keep halting in CI"],"tags":["hibernate","schema-management","ddl","hbm2ddl","halt-on-error"],"backgroundTag":"ddl-execution-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}