Setting Up & Configuration

Setting up dependencies and application properties.

Dependency

Add library as dependency to Maven or Gradle. See the actual versions on Maven Central. Add it along with repository in your dependency manager. Java 17 or higher is required to use this library.

Version problem4j-spring-v1.x is backwards compatible down to Spring Boot 3.0.x, although it was tested mostly on versions between 3.2.x and 3.5.x. Integration with Spring Boot 4 is released as problem4j-spring-v2.x.

Spring Boot Version	Problem4J Spring Version
3.x	1.x (latest - 1.2.0)
4.x	2.x (latest - 2.1.0)

Use version from the above table while managing your dependency or visit Maven Central to find out latest version in given generation.

1. Maven:

   <dependencies>
       <!-- pick the one for your project -->
       <dependency>
           <groupId>io.github.problem4j</groupId>
           <artifactId>problem4j-spring-webflux</artifactId>
           <version>{version}</version>
       </dependency>
       <dependency>
           <groupId>io.github.problem4j</groupId>
           <artifactId>problem4j-spring-webmvc</artifactId>
           <version>{version}</version>
       </dependency>
   </dependencies>

2. Gradle (Kotlin DSL):

   dependencies {
       // pick the one for your project
       implementation("io.github.problem4j:problem4j-spring-webflux:{version}")
       implementation("io.github.problem4j:problem4j-spring-webmvc:{version}")
   }

Note: To limit the number of transitive dependencies, you need to include Spring Boot explicitly in your project.

Configuration

Library can be configured with following properties.

problem4j.enabled

Property that enables or disables all auto-configurations provided by this module. Defaults to true (enabled).

problem4j.detail-format

Property that specifies how exception handling imported with this module should print the "detail" field of the Problem model (lowercase, capitalized - default, uppercase). Useful for keeping a consistent style between errors generated by the library and those from your application.

problem4j.tracing-header-name

Property that specifies the name of the HTTP header used for tracing requests. If set, the trace identifier from this header is extracted and made available within the request context (ProblemContext). This value can be referenced in other configuration properties using the {context.traceId} placeholder. Defaults to null (disabled).

See Simple Tracing chapter for more info.

problem4j.type-override

Defines a template for overriding the "type" field of Problem responses. Useful for mapping logical problem identifiers to environment-specific URIs (for example, production vs. staging). Defaults to null (disabled).

See Problem Post-Processor chapter for more info.

problem4j.instance-override

Defines a template for overriding the "instance" field of Problem responses. Useful for appending runtime context such as request trace identifiers or constructing predictable instance URIs. Defaults to null (disabled).

See Problem Post-Processor chapter for more info.

problem4j.resolver-caching.enabled

Enables caching of resolved ProblemResolver instances to avoid repeated reflection and lookup. Defaults to false (disabled). When disabled, every resolution performs a fresh lookup. Enable if you have many repeated resolutions of a stable set of exception / resolver types.

See Resolver Caching chapter for more info.

problem4j.resolver-caching.max-cache-size

Maximum number of resolver entries stored when caching is enabled. Defaults to -1 (unbounded). Uses LRU (least recently used) eviction once the limit is exceeded. Values <= 0 mean the cache is unbounded (no eviction).

Note that in most cases, there's no need to ever limit max cache size for problem resolvers, as the number of resolvers or exception types never increase at runtime.

See Resolver Caching chapter for more info.