Failures and errors

The Kalix Java SDK has two mechanisms dealing with something going wrong.


The first one is more or less expected errors. For example validation errors: an incoming request not fulfilling the requirements or the state of the receiving not allowing the command to be handled. Such errors should be signalled back to the user as an error effect of the component using the effects().error(description) function. The HTTP request is responded to with a failure response with the error description as response body. Nothing is logged by Kalix for such errors.


The second one is unexpected failures, represented by an Exception thrown when a request was handled. When such failures happen in the user defined logic of the service the details of the exception is hidden from the client, to not leak internal details of how the service is implemented, and instead a non-descriptive failure message is returned to the client.

The internal details are instead logged at error level by the SDK SLF4J logger.

In the non-descriptive message to the user a correlation ID is included, for example, the response could look like this:

Unexpected error [2c74bdfb-3130-464c-8852-cf9c3c2180ad]

That same correlation ID 2c74bdfb-3130-464c-8852-cf9c3c2180ad is included in the error log entry for the error as an MDC value with the key correlationID. This makes it possible to find the specific error in the logs using kalix logs or by querying your configured logging backend for the service.