Troubleshooting

No Fingerprint Is Logged

Check:

1. The Spring starter dependency is present.
2. The application is a servlet MVC or reactive WebFlux web application.
3. bugdna.enabled is not false.
4. bugdna.log-enabled is not false.
5. Error logging is enabled for io.github.bugdna.spring.BugDnaExceptionLogger.

Automatic capture covers unhandled Spring MVC and WebFlux web exceptions. It does not cover non-web background exceptions or reactive errors consumed by onErrorResume, onErrorReturn, or another local recovery operator. Use BugDnaSpringService or FailureTracker manually for those paths.

try {
    runBackgroundTask();
} catch (RuntimeException failure) {
    Fingerprint fingerprint = bugDna.fingerprint(failure);
    log.error("Background task failed [{}]", fingerprint.getId(), failure);
}

No WebFlux Fingerprint Is Logged

Check:

1. spring-boot-starter-webflux is present.
2. The application type is reactive, not servlet.
3. bugdna.enabled and bugdna.log-enabled are not false.
4. The error reaches the global WebFlux exception chain.

Errors handled locally do not reach the automatic handler:

return operation()
        .doOnError(bugDna::fingerprint)
        .onErrorResume(this::fallback);

When both MVC and WebFlux dependencies are present, Spring Boot commonly selects the servlet application type unless spring.main.web-application-type=reactive is configured.

FailureTracker Bean Is Missing

Confirm core BugDNA auto-configuration is enabled. The bean is not created when:

bugdna.enabled=false

Applications may also provide their own FailureTracker bean.

MDC Value Is Empty

MDC keys are present only during BugDNA's automatic log call and are removed afterward. Include %X{bugdna} in the logging pattern:

logging.pattern.console=%-5level [%X{bugdna}] %logger{36} - %msg%n

Direct calls to BugDna.generate(...) do not modify MDC.

Actuator Endpoint Returns 404

Creating an endpoint and exposing it are separate steps:

management.endpoints.web.exposure.include=health,bugdna

Also verify that Spring Boot Actuator is on the classpath.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Then test the endpoint directly:

curl -i http://localhost:8080/actuator/bugdna

Prometheus Metrics Are Missing

Check that:

• A Micrometer MeterRegistry bean exists
• The Prometheus registry dependency is installed
• The Prometheus endpoint is exposed
• At least one failure has been recorded

Prometheus names use underscores:

bugdna_failures_total
bugdna_unique_failures

Required registry dependency:

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

Verify the raw endpoint:

curl http://localhost:8080/actuator/prometheus

Counts Reset

This is expected after restart. Trackers, recent snapshots, and metrics are all in-memory. Export metrics to monitoring storage when historical retention is needed.

Similar Failures Have Different IDs

Class names, method names, and normalized call paths affect identity. Compare the fingerprints with BugDiff.compare(...) or BugSimilarity.compare(...).

FingerprintDiff diff = BugDiff.compare(firstFailure, secondFailure);
System.out.println(diff.explain());

Similarity similarity = BugSimilarity.compare(
        BugDna.generate(firstFailure),
        BugDna.generate(secondFailure)
);
System.out.println(similarity.getExplanation());

Maven Cannot Resolve Spring Boot Dependencies

Run Maven with errors enabled:

mvn -e clean test

If the error names repo.maven.apache.org, test Maven Central from the same machine:

curl -I https://repo.maven.apache.org/maven2/

Then check the Spring Boot BOM version configured in the root pom.xml:

<spring-boot.version>4.0.6</spring-boot.version>

Corporate proxy or repository-mirror settings belong in ~/.m2/settings.xml. A 401 or 403 usually indicates repository credentials or mirror policy; a DNS or connection timeout indicates network or proxy configuration.