Make a call on an unknown API to get a 404

Oct 13, 2025 by thesweetdesigns.com 136 views

Introduction

When enabling reporting of not found requests in Gravitee, you may encounter an error that prevents the reporting of 404 responses. This issue is caused by a problem with the Freemarker template used to generate the report. In this article, we will explore the steps to reproduce this issue and provide additional information to help you troubleshoot and resolve the problem.

Description

The error occurs when the gravitee_handlers_notfound_analytics_enabled option is set to true. When a 404 response is received, the reporting mechanism attempts to generate a report using the Freemarker template v4-metrics.ftl. However, the template fails to generate the report due to an InvalidReferenceException caused by a null or missing value.

Steps to reproduce

To reproduce this issue, follow these steps:

Start a gateway with the gravitee_handlers_notfound_analytics_enabled option set to true: This option enables the reporting of not found requests. You can set this option in the Gravitee configuration file or using the Gravitee Management Console.
Make a call on an unknown API to get a 404: Use a tool like Postman or cURL to make a request to an unknown API. This will trigger a 404 response, which should be reported by the Gravitee gateway.
Look at the Management Console dashboard; nothing appears: According to APIM-5601, the Management Console dashboard should display the reported 404 responses. However, in this case, nothing appears.
Look at the gateway’s logs; the above stacktrace appears: The gateway's logs will display the stacktrace shown below.

Stacktrace

The stacktrace is as follows:

13:32:33.727 [vert.x-worker-thread-19] [] WARN  i.g.r.common.bulk.BulkProcessor - Unable to format incoming reportable
java.lang.IllegalArgumentException: Impossible to generate from template v4-metrics.ftl
	at io.gravitee.common.templating.FreeMarkerComponent.generateFromTemplate(FreeMarkerComponent.java:87)
	at io.gravitee.reporter.common.formatter.elasticsearch.ElasticsearchFormatter.generateData(ElasticsearchFormatter.java:422)
	at io.gravitee.reporter.common.formatter.elasticsearch.ElasticsearchFormatter.getSource(ElasticsearchFormatter.java:358)
	at io.gravitee.reporter.common.formatter.elasticsearch.ElasticsearchFormatter.format0(ElasticsearchFormatter.java:108)
	at io.gravitee.reporter.common.formatter.AbstractFormatter.format(AbstractFormatter.java:55)
	at io.gravitee.reporter.common.bulk.transformer.BulkFormatterTransformer.transform(BulkFormatterTransformer.java:37)
	at io.gravitee.reporter.common.bulk.BulkProcessor.lambda$transform$3(BulkProcessor.java:96)
	at io.reactivex.rxjava3.internal.operators.maybe.MaybeFromCallable.subscribeActual(MaybeFromCallable.java:47)
	at io.reactivex.rxjava3.core.Maybe.subscribe(Maybe.java:5377)
	at io.reactivex.rxjava3.internal.operators.maybe.MaybeFilter.subscribeActual(MaybeFilter.java:39)
	at io.reactivex.rxjava3.core.Maybe.subscribe(Maybe.java:5377)
	at io.reactivex.rxjava3.internal.operators.maybe.MaybePeek.subscribeActual(MaybePeek.java:56)
	at io.reactivex.rxjava3.core.Maybe.subscribe(Maybe.java:5377)
	at io.reactivex.rxjava3.internal.operators.maybe.MaybeOnErrorComplete.subscribeActual(MaybeOnErrorComplete.java:40)
	at io.reactivex.rxjava3.core.Maybe.subscribe(Maybe.java:5377)
	at io.reactivex.rxjava3.internal.operators.flowable.FlowableFlatMapMaybe$FlatMapMaybeSubscriber.onNext(FlowableFlatMapMaybe.java:131)
	at io.reactivex.rxjava3.internal.operators.flowable.FlowableObserveOn$ObserveOnSubscriber.runAsync(FlowableObserveOn.java:403)
	at io.reactivex.rxjava3.internal.operators.flowable.FlowableObserveOn$BaseObserveOnSubscriber.run(FlowableObserveOn.java:178)
	at io.vertx.rxjava3.ContextScheduler$ContextWorker$TimedAction.run(ContextScheduler.java:189)
	at io.vertx.rxjava3.ContextScheduler$ContextWorker$TimedAction.lambda$execute$1(ContextScheduler.java:174)
	at io.vertx.core.impl.ContextImpl.lambda$executeBlocking$5(ContextImpl.java:205)
	at io.vertx.core.impl.ContextInternal.dispatch(ContextInternal.java:270)
	at io.vertx.core.impl.ContextImpl$1.execute(ContextImpl.java:221)
	at io.vertx.core.impl.WorkerTask.run(WorkerTask.java:56)
	at io.vertx.core.impl.TaskQueue.run(TaskQueue.java:81)
	at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1144)
	at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:642)
	at io.netty.util.concurrent.FastThreadLocalRunnable.run(FastThreadLocalRunnable.java:30)
	at java.base/java.lang.Thread.run(Thread.java:1583)
Caused by: freemarker.core.InvalidReferenceException: The following has evaluated to null or missing:
==&gt; metrics.getApiName()  [in template "v4-metrics.ftl" at line 30, column 18]

Additional information

This issue is related to APIM-3932. The problem is caused by the fact that the API ID is set to 1, but no API name is provided. This breaks the Freemarker template, which expects the API name to be available.

Conclusion

Q&A

Q: What is the cause of the Fail to report NotFound request issue in Gravitee? A: The issue is caused by a problem with the Freemarker template used to generate the report. The template fails to generate the report due to an InvalidReferenceException caused by a null or missing value.

Q: What is the error message that appears in the gateway's logs? A: The error message is as follows:

13:32:33.727 [vert.x-worker-thread-19] [] WARN  i.g.r.common.bulk.BulkProcessor - Unable to format incoming reportable
java.lang.IllegalArgumentException: Impossible to generate from template v4-metrics.ftl
	at io.gravitee.common.templating.FreeMarkerComponent.generateFromTemplate(FreeMarkerComponent.java:87)
	at io.gravitee.reporter.common.formatter.elasticsearch.ElasticsearchFormatter.generateData(ElasticsearchFormatter.java:422)
	at io.gravitee.reporter.common.formatter.elasticsearch.ElasticsearchFormatter.getSource(ElasticsearchFormatter.java:358)
	at io.gravitee.reporter.common.formatter.elasticsearch.ElasticsearchFormatter.format0(ElasticsearchFormatter.java:108)
	at io.gravitee.reporter.common.formatter.AbstractFormatter.format(AbstractFormatter.java:55)
	at io.gravitee.reporter.common.bulk.transformer.BulkFormatterTransformer.transform(BulkFormatterTransformer.java:37)
	at io.gravitee.reporter.common.bulk.BulkProcessor.lambda$transform$3(BulkProcessor.java:96)
	at io.reactivex.rxjava3.internal.operators.maybe.MaybeFromCallable.subscribeActual(MaybeFromCallable.java:47)
	at io.reactivex.rxjava3.core.Maybe.subscribe(Maybe.java:5377)
	at io.reactivex.rxjava3.internal.operators.maybe.MaybeFilter.subscribeActual(MaybeFilter.java:39)
	at io.reactivex.rxjava3.core.Maybe.subscribe(Maybe.java:5377)
	at io.reactivex.rxjava3.internal.operators.maybe.MaybePeek.subscribeActual(MaybePeek.java:56)
	at io.reactivex.rxjava3.core.Maybe.subscribe(Maybe.java:5377)
	at io.reactivex.rxjava3.internal.operators.maybe.MaybeOnErrorComplete.subscribeActual(MaybeOnErrorComplete.java:40)
	at io.reactivex.rxjava3.core.Maybe.subscribe(Maybe.java:5377)
	at io.reactivex.rxjava3.internal.operators.flowable.FlowableFlatMapMaybe$FlatMapMaybeSubscriber.onNext(FlowableFlatMapMaybe.java:131)
	at io.reactivex.rxjava3.internal.operators.flowable.FlowableObserveOn$ObserveOnSubscriber.runAsync(FlowableObserveOn.java:403)
	at io.reactivex.rxjava3.internal.operators.flowable.FlowableObserveOn$BaseObserveOnSubscriber.run(FlowableObserveOn.java:178)
	at io.vertx.rxjava3.ContextScheduler$ContextWorker$TimedAction.run(ContextScheduler.java:189)
	at io.vertx.rxjava3.ContextScheduler$ContextWorker$TimedAction.lambda$execute$1(ContextScheduler.java:174)
	at io.vertx.core.impl.ContextImpl.lambda$executeBlocking$5(ContextImpl.java:205)
	at io.vertx.core.impl.ContextInternal.dispatch(ContextInternal.java:270)
	at io.vertx.core.impl.ContextImpl$1.execute(ContextImpl.java:221)
	at io.vertx.core.impl.WorkerTask.run(WorkerTask.java:56)
	at io.vertx.core.impl.TaskQueue.run(TaskQueue.java:81)
	at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1144)
	at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:642)
	at io.netty.util.concurrent.FastThreadLocalRunnable.run(FastThreadLocalRunnable.java:30)
	at java.base/java.lang.Thread.run(Thread.java:1583)
Caused by: freemarker.core.InvalidReferenceException: The following has evaluated to null or missing:
==&gt; metrics.getApiName()  [in template "v4-metrics.ftl" at line 30, column 18]

Q: What is the solution to this issue? A: To resolve this issue, you need to provide the API name for the API ID 1. This can be done by updating the API configuration or by modifying the Freemarker template to handle the missing API name.

Q: How can I update the API configuration to provide the API name? A: You can update the API configuration by modifying the API's metadata to include the API name. This can be done using the Gravitee Management Console or by modifying the API's configuration file.

Q: How can I modify the Freemarker template to handle the missing API name? A: You can modify the Freemarker template by adding a default value for the API name or by using a conditional statement to check if the API name is available before using it.

Q: What is the impact of this issue on the Gravitee gateway? A: The impact of this issue is that the Gravitee gateway will not be able to report NotFound requests correctly. This can lead to incorrect metrics and analytics being displayed in the Gravitee Management Console.

Q: How can I troubleshoot this issue? A: To troubleshoot this issue, you can check the gateway's logs for any error messages related to the Freemarker template. You can also use the Gravitee Management Console to check the API's configuration and metadata to ensure that the API name is correctly set.