{"record":{"id":"5d754d2c295c80fd","repo":"hibernate/hibernate-orm","slug":"unknown-tccllookupprecedence","errorCode":null,"errorMessage":"Unknown TcclLookupPrecedence - {}","messagePattern":"Unknown TcclLookupPrecedence - (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/registry/classloading/internal/TcclLookupPrecedence.java","lineNumber":69,"sourceCode":"\t * @return The precedence, or {@code defaultValue} if none was specified.\n\t * @throws IllegalArgumentException If there is a setting defined for\n\t * precedence, but it is not a legal value\n\t */\n\tpublic static TcclLookupPrecedence from(Map<?,?> settings, TcclLookupPrecedence defaultValue) {\n\t\tfinal String explicitSetting = (String) settings.get( AvailableSettings.TC_CLASSLOADER );\n\t\tif ( explicitSetting == null ) {\n\t\t\treturn defaultValue;\n\t\t}\n\n\t\tif ( NEVER.name().equalsIgnoreCase( explicitSetting ) ) {\n\t\t\treturn NEVER;\n\t\t}\n\n\t\tif ( BEFORE.name().equalsIgnoreCase( explicitSetting ) ) {\n\t\t\treturn BEFORE;\n\t\t}\n\n\t\tthrow new IllegalArgumentException( \"Unknown TcclLookupPrecedence - \" + explicitSetting );\n\t}\n}\n","sourceCodeStart":51,"sourceCodeEnd":72,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/registry/classloading/internal/TcclLookupPrecedence.java#L51-L72","documentation":"TcclLookupPrecedence controls when the thread-context ClassLoader is consulted by Hibernate's aggregated ClassLoader. The value is read from the setting hibernate.classLoader.tccl_lookup_precedence (AvailableSettings.TC_CLASSLOADER), and this implementation accepts only the explicit strings NEVER and BEFORE (case-insensitive); anything else - including a literal 'after' - throws IllegalArgumentException. When the property is absent, the default (AFTER, applied by BootstrapServiceRegistryBuilder/PersistenceXmlParser) is used silently.","triggerScenarios":"Setting hibernate.classLoader.tccl_lookup_precedence in persistence.xml, hibernate.cfg.xml, or the settings map to any value other than never/before - e.g. 'after', 'true', 'always', or a typo - during TcclLookupPrecedence.from(settings) at bootstrap.","commonSituations":"Typo'd or legacy values copied from other frameworks; assuming 'AFTER' is an accepted literal in this version; XML/YAML quoting or trailing whitespace corrupting the value; classloader troubleshooting cargo-culted from old blog posts.","solutions":["Set the property to never or before (case-insensitive), or remove it entirely to accept the default precedence","Check the property source for trailing whitespace, quotes, or casing artifacts","Upgrade Hibernate if you need a version that accepts the explicit 'after' literal"],"exampleFix":"// before\n<property name=\"hibernate.classLoader.tccl_lookup_precedence\" value=\"after\"/> <!-- rejected -->\n\n// after\n<!-- omit the property for the default (AFTER), or use: -->\n<property name=\"hibernate.classLoader.tccl_lookup_precedence\" value=\"before\"/>","handlingStrategy":"validation","validationCode":"// Validate the enum-like property before boot\nObject v = settings.get(\"hibernate.classLoader.tccl_lookup_precedence\");\nif (v != null) {\n    String s = v.toString().trim();\n    if (!(\"never\".equalsIgnoreCase(s) || \"before\".equalsIgnoreCase(s))) {\n        throw new IllegalStateException(\n            \"hibernate.classLoader.tccl_lookup_precedence must be never or before, got: \" + s);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    TcclLookupPrecedence.from(settings);\n} catch (IllegalArgumentException e) {\n    // strip the property and retry with the default to unblock boot, then fix the value\n    settings.remove(\"hibernate.classLoader.tccl_lookup_precedence\");\n    throw e;\n}","preventionTips":["Treat the TCCL precedence property as an enum: only never/before accepted explicitly","Add config validation (Spring Boot metadata / OWASP-style checks) that whitelists known enum values","Beware literal 'after' - omit the property to get the default precedence"],"tags":["hibernate","configuration","classloading","boot","property"],"backgroundTag":"invalid-config-value","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}