The H2 database is an in-memory database widely used during Spring Boot development for quick prototyping. Spring Boot conveniently provides an H2 console that you can access via the browser at /h2-console. However, developers often face a problem where the console doesn’t show up or throws an error when accessed. Let us delve into understanding the common Spring Boot H2 console error and how to resolve it effectively.
1. What is H2 Database?
H2 is a lightweight, fast, and open-source relational database engine written in Java. It is widely used for development and testing purposes due to its in-memory capabilities, which allow for quick setup without the need for external database installation. H2 can be embedded directly into Java applications or run in client-server mode. It supports standard SQL and provides a web-based console that makes it easy to interact with the database through a browser interface. In Spring Boot applications, H2 is often used during development for rapid prototyping and testing of persistence logic without relying on external database servers.
2. Understanding and Simulating the Error
Let’s start by creating a simple Spring Boot application with the H2 database dependency.
2.1 Add H2 Dependency
To use the H2 database in your Spring Boot application, you need to add the H2 dependency to your pom.xml file. This provides support for an in-memory database along with a convenient web-based console for database interaction.
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<scope>runtime</scope>
</dependency>
By setting the scope to runtime, H2 is only included when the application is running, which is ideal for development and testing scenarios. No external installation is needed; everything runs in memory.
2.2 application.properties
Next, configure H2 in src/main/resources/application.properties. These settings control the behavior of the H2 console and the in-memory database itself.
spring.h2.console.enabled=true spring.h2.console.path=/h2-console spring.datasource.url=jdbc:h2:mem:testdb spring.datasource.driverClassName=org.h2.Driver spring.datasource.username=sa spring.datasource.password=
spring.h2.console.enabled=true– Enables the H2 web console.spring.h2.console.path=/h2-console– Specifies the browser path to access the console.spring.datasource.url=jdbc:h2:mem:testdb– Points to an in-memory database namedtestdb.spring.datasource.driverClassName=org.h2.Driver– Sets the JDBC driver for H2.spring.datasource.usernameandpassword– Credentials for connecting to the H2 database (defaults tosawith no password).
Now, if you run your Spring Boot application and navigate to http://localhost:8080/h2-console, you should ideally see the H2 console login screen. However, many developers encounter the following error in the browser’s console:
Refused to display 'http://localhost:8080/h2-console' in a frame because it set 'X-Frame-Options' to 'DENY'.
This error indicates that the page cannot be displayed in a frame due to Spring Security’s default HTTP header settings. Specifically, the X-Frame-Options header is set to DENY, preventing the H2 console from rendering properly in the browser.
To fix this, you’ll need to adjust your Spring Security configuration to allow the H2 console to be embedded in a frame. We’ll cover this solution in the next section.
2.3 Fixing the Error by Disabling X-Frame-Options
You need to customize Spring Security to allow the H2 console to load within a frame. This can be done by overriding the default Spring Security configuration. by overriding the default Spring Security configuration.
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
@Configuration
public class SecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests(auth -> auth
.requestMatchers("/h2-console/**").permitAll()
.anyRequest().authenticated()
)
.csrf(csrf -> csrf
.ignoringRequestMatchers("/h2-console/**")
)
.headers(headers -> headers
.frameOptions(frame -> frame
.sameOrigin()
)
);
return http.build();
}
}
2.3.1 Code Explanation
The above code defines a custom Spring Security configuration using a class annotated with @Configuration. Inside it, a SecurityFilterChain bean is created to customize HTTP security settings. The authorizeHttpRequests method allows unrestricted access to the /h2-console/** path while requiring authentication for all other requests. The csrf configuration disables CSRF protection specifically for the H2 console path to prevent form submission issues. Additionally, the headers section configures the X-Frame-Options header to sameOrigin, which is essential for allowing the H2 web console to load within a frame from the same domain. This setup resolves the “spring boot h2 console error” caused by frame restrictions and makes the console accessible in the browser during development.
2.3.2 Code Output
After restarting your application, visit:
http://localhost:8080/h2-console
You should now see the H2 login screen properly rendered in your browser:
- JDBC URL: jdbc:h2:mem:testdb
- User Name: sa
- Password: (leave blank)
Click “Connect” to start querying your in-memory database.
3. Conclusion
If the H2 console is not showing up in your Spring Boot application, the issue is likely due to Spring Security’s default frame options. You can fix it by customizing the security configuration to allow frame embedding from the same origin.
