{"record":{"id":"068b273e7c48ac4c","repo":"hibernate/hibernate-orm","slug":"unique-suffix-s-length-must-be-less-than-maximu","errorCode":null,"errorMessage":"Unique suffix [%s] length must be less than maximum [%d]","messagePattern":"Unique suffix \\[(.+?)\\] length must be less than maximum \\[(.+?)\\]","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/mapping/Column.java","lineNumber":227,"sourceCode":"\t\telse {\n\t\t\tfinal String lowerCaseName = name.toLowerCase( Locale.ROOT );\n\t\t\treturn lowerCaseName.length() > lastLetter + 1\n\t\t\t\t\t? lowerCaseName.substring( 0, lastLetter + 1 )\n\t\t\t\t\t: lowerCaseName;\n\t\t}\n\t}\n\n\tprivate @Nonnull String qualifyAlias(Dialect dialect, String suffix, String alias) {\n\t\tfinal int suffixLength = suffix.length();\n\t\tfinal int maxAliasLength = dialect.getMaxAliasLength();\n\t\tfinal int freeLength = maxAliasLength - suffixLength;\n\t\tfinal boolean useRawName =\n\t\t\t\tname.length() <= freeLength\n\t\t\t\t&& !quoted\n\t\t\t\t&& !name.equalsIgnoreCase( dialect.rowId(null) );\n\t\tif ( !useRawName ) {\n\t\t\tif ( suffixLength >= maxAliasLength ) {\n\t\t\t\tthrow new MappingException(\n\t\t\t\t\t\tString.format(\n\t\t\t\t\t\t\t\t\"Unique suffix [%s] length must be less than maximum [%d]\",\n\t\t\t\t\t\t\t\tsuffix, maxAliasLength\n\t\t\t\t\t\t)\n\t\t\t\t);\n\t\t\t}\n\t\t\tif ( alias.length() > freeLength ) {\n\t\t\t\treturn alias.substring( 0, freeLength ) + suffix;\n\t\t\t}\n\t\t}\n\t\treturn alias + suffix;\n\t}\n\n\t/**\n\t * Generate a column alias that is unique across multiple tables\n\t */\n\t@Override\n\tpublic String getAlias(Dialect dialect, Table table) {","sourceCodeStart":209,"sourceCodeEnd":245,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/mapping/Column.java#L209-L245","documentation":"When Hibernate must shorten a column alias to honor dialect.getMaxAliasLength(), it appends a short unique suffix to keep aliases distinct. If the suffix itself is at least as long as the maximum alias length, no valid alias can be produced and bootstrap fails with this MappingException.","triggerScenarios":"A dialect with a very small maxAliasLength (or a custom dialect misreporting it) combined with long or quoted column names that force the truncation path; rowid-like names; many duplicate truncated aliases producing longer generated suffixes.","commonSituations":"Oracle-family dialects (12/30-character limits) with very long generated names from long entity/field names; applications extending an outdated Oracle dialect; result set mappings selecting many similarly-named columns.","solutions":["Shorten column names via @Column so no truncation is needed.","Use or extend a current dialect matching the actual database version so getMaxAliasLength() reports correctly.","As a last resort, override alias generation in a custom dialect."],"exampleFix":"// before (12-char alias budget)\n@Column(name = \"customer_primary_contact_telephone\")\nprivate String primaryContactPhone;\n\n// after\n@Column(name = \"prim_phone\")\nprivate String primaryContactPhone;","handlingStrategy":"validation","validationCode":"int maxAlias = dialect.getMaxAliasLength();\n// keep generated column names comfortably below maxAlias to avoid truncated-alias suffixing\nif ( columnName.length() + 4 >= maxAlias ) {\n    log.warn( \"Column name {} is close to alias limit {}\", columnName, maxAlias );\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep column names short by convention (@Column with concise names)","Run schema export and query smoke tests against the production dialect in CI","Use a dialect version that matches the actual database"],"tags":["hibernate","dialect","alias","oracle"],"backgroundTag":"identifier-too-long","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}