"WFLYJCA0114: Failed to load datasource class: ..." referencing unused class in JBoss EAP

Environment

• Red Hat JBoss Enterprise Application Platform (EAP) 7.2 (and later)

Issue

• Encountering a datasource add/deployment failure indicating a missing driver

  ... "WFLYCTL0412: Required services that are not installed:" => [
      "jboss.jdbc-driver.oracle",
      "jboss.jdbc-driver.oracle"
  ],
  "WFLYCTL0180: Services with missing/unavailable dependencies" => [
      "org.wildfly.data-source.MyDS is missing [jboss.jdbc-driver.oracle]",
      "jboss.driver-demander.java:/jdbc/MyDS is missing [jboss.jdbc-driver.oracle]",
      "org.wildfly.data-source.MyDS is missing [jboss.jdbc-driver.oracle]"
  ]
  

• Earlier in the server.log the following error was found

  ... ERROR [org.jboss.as.controller.management-operation] ... WFLYCTL0013: Operation ("add") failed - address: ([
      ("subsystem" => "datasources"),
      ("jdbc-driver" => "oracle")
  ]) - failure description: "WFLYJCA0114: Failed to load datasource class: oracle.jdbc.OracleDriver"
  

• oracle.jdbc.OracleDriver was specified as an xa-datasource-class but no XA pool has been defined so the class should not be used.

• The same configuration worked in older EAP releases (prior to JBoss EAP 7.2).

Resolution

• If creating an XA datasource pool, verify that a valid <xa-datasource-class> is specified in the relevant entry in the <drivers> configuration (at the bottom of the datasources subsection) or else within the <xa-datasource> configuration. Refer to the XA datasource examples in the JBoss EAP Configuration Guide.
• If creating a non-XA datasource pool, remove <driver-class> and <datasource-class> references (from both the <datasource> and the relevant entry in the <drivers> configuration). JDBC 4 compliant drivers specify their preferred connection provider in the driver JAR's META-INF/services/java.sql.Driver file. Only if the driver is not JDBC 4 compliant should a provider class be required for non-XA datasource pools. In such cases, consult the 3rd party driver vendor's documentation for an appropriate class. Note that a driver-class would be preferred rather than a datasource-class when a provider class must be specified.

Root Cause

• An invalid datasource-class or xa-datasource-class was specified (e.g. in the example above, an Oracle class implementing the Content from docs.oracle.com is not included.java.sql.Driver interface was specified as xa-datasource-class and this class cannot be cast to Content from docs.oracle.com is not included.javax.sql.XADataSource).
• The WFLYJCA0114 error is the result of enhanced Content from github.com is not included.validation in EAP 7.2 and later - any explicitly specified datasource-class or xa-datasource-class in a driver configuration will be loaded for verification.
  • In EAP releases earlier than EAP 7.2, only explicitly provided driver-class-name properties were validated and invalid datasource-class or xa-datasource-class properties were ignored until/unless used (e.g. if an XA pool was specified the xa-datasource-class would be accessed).
• The WFLYCTL0412 / WFLYCTL0180 pair result from the failed driver deployment (since the driver isn't deployed, the datasource which depends on it cannot be deployed).

Diagnostic Steps

For the class mentioned in the "Failed to load" message:

1. Verify that the class specified exists in the driver JAR file.
2. Verify that the class specified implements the correct interface¹. This can often be accomplished using javap -cp <jar_file> <fully.qualified.class> for the class (and its super-classes or super-interfaces).

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.