During application deployment on WildFly or Red Hat JBoss EAP, one of the most generic and frequent deployment failures is ERROR [org.jboss.msc.service.fail] MSC000001: Failed to start service jboss.deployment.unit. Because this error wraps around the underlying Modular Service Container (MSC), finding the actual root cause requires understanding which deployment phase failed.

⚡ Quick Troubleshooting Strategy

Look at the suffix appended to the deployment unit service name (e.g., PARSE, DEPENDENCIES, INSTALL). The suffix tells you when the server failed: during XML reading (PARSE), missing subsystem/module binding (DEPENDENCIES), or runtime code initialization failure (INSTALL).

1. Decoding WildFly Deployment Phases

WildFly processes applications through a chain of phases managed by the JBoss MSC. Identifying the suffix in the log instantly narrows down your troubleshooting scope:

Phase Suffix What WildFly is doing Common Root Causes
.PARSE Reading XML deployment descriptors or scanning annotations. Syntax errors in web.xml, invalid characters in *-ds.xml, or missing required XML tags.
.DEPENDENCIES Resolving required server modules, JDBC datasources, or JMS queues. Missing JBoss modules, missing Resource Adapters, or using a standalone profile lacking the required subsystem (e.g. standalone.xml instead of standalone-full.xml).
.POST_MODULE Applying classloading and byte-code enhancements. Class Version Mismatch (e.g. compiled with Java 21 on Java 17 server) or legacy javax.* vs jakarta.* namespace conflicts.
.INSTALL Bootstrapping application components, EJB/CDI beans, and Spring contexts. Exceptions thrown during @PostConstruct methods, failed database connections, or Spring Context initialization crashes.

2. Real-World Failure Examples & Solutions

Scenario A: Missing Subsystem or Resource Adapter (.PARSE / .DEPENDENCIES)

Consider the following trace when deploying a Message-Driven Bean (MDB) application:

16:55:43,642 ERROR [org.jboss.msc.service.fail] (MSC service thread 1-1) MSC000001: Failed to start service jboss.deployment.unit."helloworld-mdb.war".PARSE: org.jboss.msc.service.StartException in service jboss.deployment.unit."helloworld-mdb.war".PARSE: WFLYSRV0153: Failed to process phase PARSE of deployment "helloworld-mdb.war"
    at org.jboss.as.server@18.0.4.Final//org.jboss.as.server.deployment.DeploymentUnitPhaseService.start(DeploymentUnitPhaseService.java:189)
    ...
Caused by: org.jboss.msc.service.ServiceNotFoundException: service jboss.ejb.default-resource-adapter-name-service not found

Root Cause: The application requires messaging capability (EJB MDB), but WildFly was started using a profile that lacks the ActiveMQ/Artemis messaging subsystem (e.g., standalone.xml instead of standalone-full.xml).

Solution: Start WildFly using the full profile configuration:

$ ./standalone.sh -c standalone-full.xml

Scenario B: Invalid XML Configuration Descriptor (.PARSE)

Here is an example triggered by an inline XML datasource descriptor or bad web.xml syntax:

ERROR [org.jboss.msc.service.fail] (MSC service thread 1-7) MSC00001: Failed to start service jboss.deployment.unit."mysql-ds.xml".PARSE: org.jboss.msc.service.StartException in service jboss.deployment.unit."mysql-ds.xml".PARSE: Failed to process phase PARSE of deployment "mysql-ds.xml"
    at org.jboss.as.server.deployment.DeploymentUnitPhaseService.start(DeploymentUnitPhaseService.java:119)
    ...
Caused by: org.jboss.as.server.deployment.DeploymentUnitProcessingException: Received non-all-whitespace CHARACTERS or CDATA event in nextTag(). at [row,col {unknown source}]: [95,0]

Root Cause: Malformed XML syntax or illegal hidden characters at line 95 of mysql-ds.xml.

Solution: Validate the descriptor against the WildFly XML schema definition or check line end encodings in your editor.

Scenario C: Jakarta EE Namespace Mismatch on Modern WildFly

Starting with WildFly 27+, the server runs natively on Jakarta EE 10/11 (using jakarta.* packages). Deploying a legacy WAR containing javax.servlet.* or javax.persistence.* without auto-transformation causes deployment failures during the component discovery phase.

Solution: Either update your dependencies to Jakarta EE or enable the bytecode transformation flag in WildFly Preview distributions.

Scenario D: Classloading Conflicts

If your application bundles third-party libraries in WEB-INF/lib that conflict with modules provided natively by WildFly, the deployment unit will fail during class resolution.

Solution: Exclude conflicting server modules using a custom src/main/webapp/WEB-INF/jboss-deployment-structure.xml:

<jboss-deployment-structure>
    <deployment>
        <exclusions>
            <module name="org.slf4j" />
            <module name="org.apache.log4j" />
        </exclusions>
    </deployment>
</jboss-deployment-structure>

3. Diagnostic Tip: Finding the "Caused By" Chain

Complex frameworks like Spring, Hibernate, or CDI can generate dozens of nested stack traces. Follow these rules to locate the real issue quickly:

  1. Scroll down to the bottom-most Caused by: entry in your server log (standalone/log/server.log).
  2. Filter the log output for your application's base package name (e.g. grep -A 10 "Caused by: com.mycompany" server.log).
  3. Use the JBoss CLI to inspect deployment error descriptions programmatically: 
    $ ./jboss-cli.sh --connect --command="/deployment=helloworld-mdb.war:read-attribute(name=boot-time-status)"

4. Frequently Asked Questions (FAQs)

Q1: Where do I find the full deployment error stack trace?

Check the main server log file located at $WILDFLY_HOME/standalone/log/server.log. IDE console outputs often truncate long exception chains.

Q2: How do I clean failed deployments before retrying?

Remove any .failed or .undeployed marker files inside the $WILDFLY_HOME/standalone/deployments/ directory before redeploying your updated WAR/EAR archive.

Conclusion

Resolving the Failed to start service jboss.deployment.unit error requires analyzing the specific deployment phase (.PARSE, .DEPENDENCIES, or .INSTALL) and scrolling down to the root cause in server.log. By verifying subsystem profile availability, XML descriptor syntax, and classloading rules, you can quickly fix deployment failures on WildFly and JBoss EAP.