Fix Spring Boot Application Failed to Start Errors
Read the failure analysis Spring Boot prints, classify the cause in a minute and use the condition report when no analyzer matches.

The console fills with a stack trace a hundred lines long, ends with Application run failed, and the process exits. The instinct is to scroll to the bottom and search the last line. Don't. For the most common startup failures, Spring Boot has already done the analysis for you, and printed it in a boxed block above the stack trace that most people scroll past: a description of what went wrong and an action to take. When there is no such block, the stack trace has a structure that points to the cause in the last Caused by. This post teaches you to read both, matches the typical failures to their fixes with the exact text, shows how to ask Boot what it decided at startup and gives the habit that keeps a fix from turning into three. Examples use Spring Boot 4 and Java 25.
Read the two paragraphs first
When Boot recognizes a failure, a FailureAnalyzer replaces the stack trace with a report like this:
***************************
APPLICATION FAILED TO START
***************************
Description:
Web server failed to start. Port 8080 was already in use.
Action:
Identify and stop the process that's listening on port 8080 or configure this application to listen on another port.The two paragraphs, Description and Action, are the whole diagnosis. Read them slowly. The description says what failed in plain words; the action says what Boot suggests. This one has a dedicated post, port 8080 already in use, but note how little guessing was needed. Boot ships dozens of analyzers for common failures, and the list is extended by libraries.
If you do not see this block, the failure was not recognized, and you read the stack trace instead. Look for the lines beginning Caused by: and read the last one first; it is the root cause. Everything above it is the chain of frames that wrapped the original error as it travelled up.
Match the Description to a class
The text of the description tells you which kind of failure it is. These are the ones that account for most startup failures.
A dependency cannot be satisfied.
Description:
Parameter 0 of constructor in dev.javahacks.shop.OrderService required a bean of type 'dev.javahacks.shop.PaymentGateway' that could not be found.
Action:
Consider defining a bean of type 'dev.javahacks.shop.PaymentGateway' in your configuration.Boot is saying a class has a constructor parameter and no bean of that type exists. Check that the implementing class is annotated, in a scanned package and not excluded by a profile. The detailed checklist is in No qualifying bean of type.
Beans form a cycle.
Description:
The dependencies of some of the beans in the application context form a cycle:
┌─────┐
| orderService defined in file [OrderService.class]
↑ ↓
| inventoryService defined in file [InventoryService.class]
└─────┘Two beans each need the other in their constructors, so neither can be built first. Break the cycle in the design, as discussed in fixing circular dependencies; spring.main.allow-circular-references=true is a bandage, not a fix.
No database is configured.
Description:
Failed to configure a DataSource: 'url' attribute is not specified and no embedded datasource could be configured.
Reason: Failed to determine a suitable driver classYou have a JDBC starter on the classpath and no connection URL. Set spring.datasource.url, or remove the starter if you do not use a database. The full list of causes is in Failed to configure a DataSource.
A placeholder is unresolved. The message Could not resolve placeholder 'app.api-key' in value "${app.api-key}" means a ${...} reference has no value in any property source; see Could not resolve placeholder.
A bean could not be created. A BeanCreationException is a wrapper: it says that building bean X failed, and the real reason is in its cause. The reading method is in BeanCreationException and its root cause.
Java version mismatch. UnsupportedClassVersionError: ... has been compiled by a more recent version of the Java Runtime (class file version 69.0) means the build used a newer JDK than the one running it; see UnsupportedClassVersionError.
Property binding failures
A typed @ConfigurationProperties class that cannot be filled produces one of the most informative reports Boot has, and also one of the most skipped:
Description:
Binding to target [Bindable@5b8a2e4 type = dev.javahacks.config.ShopProperties] failed:
Property: shop.timeout
Value: "abc"
Origin: class path resource [application.yaml] - 4:12
Reason: failed to convert java.lang.String to java.time.Duration
Action:
Update your application's configurationIt names the property, the offending value, the exact file and line of the origin, and why the conversion failed. Open the file at line 4 and fix the value. Validation failures from @Validated properties look similar, with Reason: must not be blank. The same output appears when an environment variable overrides the file with a bad value, and Origin then names the variable, which is the quickest way to find where a surprising value came from; the precedence rules behind that are covered in the configuration precedence post.
When there is no friendly report
A startup that dies with a raw stack trace has a structure worth learning. A typical shape:
org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'orderController': Unsatisfied dependency expressed through constructor parameter 0
at ...
Caused by: org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'orderService' defined in file [...]: Failed to instantiate
at ...
Caused by: java.lang.IllegalStateException: STRIPE_KEY is not set
at dev.javahacks.shop.StripeGateway.<init>(StripeGateway.java:14)Read it bottom up. The first lines are Spring reporting which bean it was building when the problem surfaced (orderController, because it needs orderService, which needs the gateway). The last Caused by is the cause: a constructor in your own code threw IllegalStateException because an environment variable was missing. The fix is in StripeGateway's configuration, not in the controller the trace opens with. A habit to build: ignore the outer wrapper exceptions, find the last Caused by, and look for the first stack frame that belongs to your package.
Two special cases deserve a glance. If the process is gone with no trace, the operating system killed it: in a container, check for OOMKilled and the exit code 137, described in a Java container killed by the OOM killer. If it starts locally and fails only in Docker, the image or its environment differs; see a Spring Boot Docker image that does not start.
Ask Spring Boot what it did
When the message is not enough, make Boot show its reasoning. Run with --debug to get the auto-configuration condition evaluation report:
java -jar target/shop.jar --debug 2>&1 | grep -A 12 'Negative matches'Negative matches:
-----------------
DataSourceAutoConfiguration:
Did not match:
- @ConditionalOnClass did not find required class 'javax.sql.DataSource'
RedisAutoConfiguration:
Did not match:
- @ConditionalOnClass did not find required class 'org.springframework.data.redis.core.RedisOperations'The Positive matches section lists what was configured and why; Negative matches lists what was skipped and the condition that failed. If a bean you expected from an auto-configuration is missing, its negative match says which class or property is absent. For a single bean, raise the log level of the factory to see creation in order:
logging.level.org.springframework.beans.factory.support.DefaultListableBeanFactory=DEBUGand if you want the failure analyzers' work visible, logging.level.org.springframework.boot.diagnostics=DEBUG. The conditions themselves are explained in the reference on auto-configuration, and the project's how-to index lists fixes for common startup situations.
Fix one thing at a time
Startup failures stack: fixing the first reveals the second, and changing three things at once leaves you unable to tell which mattered. Work in a loop. Read the description, make one change, start again. Keep the changes small and commit nothing until it boots. If the application worked before, git diff against the last good commit is the shortest path; a failure that appeared after a dependency upgrade often has a migration note in that project's release notes. For a first project built from scratch, the sequence in Spring Boot from first project to production gives a known-good baseline to compare with.
A cheap guard against the worst of these is a startup test, which fails the build instead of the deploy:
@SpringBootTest
class ApplicationStartsTest {
@Test
void contextLoads() { }
}If contextLoads passes in CI with production-like profile settings, the wiring problems are mostly gone. It cannot catch missing environment variables, so give the test the same required properties the deployment has.
Where this does not apply
If the application starts but the first request fails, you are past startup; read the request-time exception instead. If the log says Started ShopApplication and the container is then restarted, the failure is in the probes or memory limits, not in Spring. And in a native image, a startup failure may be a missing reflection hint that the JVM build never shows; run the native test suite to find it.


