How to improve error/validation feedback?

[jamie]

Is there any way, without modifying/hacking the core, to provide users with better and more meaningful feedback when something goes wrong?

My end users don't have access to the application logs, so when an error occurs they often have to stop working until I can investigate it. In many cases, I then find that the issue is simply a basic validation error that could have been communicated directly to the user.

This is becoming quite frustrating for my users, and I can understand why. I don't think users should be expected to check logs for what are, in perhaps 90% of cases, relatively straightforward validation or data-entry errors.

To give an example of the kind of issue I'm referring to, this is one that recently stopped an end user from completing their work. I had to stop what I was doing to investigate it and explain the problem, resulting in several hours of lost productivity:

[2026-09-02 13:18:36] ALERT: (0) Address cannot have more than 3 lines :: POST /Invoice/6a916f046c8031e7a/validateEInvoice :: /var/www/html/custom/Espo/Modules/Sales/vendor/josemmo/einvoicing/src/Traits/PostalAddressTrait.php(31)


In this case, the actual problem was simply that the address contained more than three lines. Ideally, the user should have received a clear message such as:

"The address cannot contain more than 3 lines. Please shorten the address and try again."

rather than a generic error requiring someone with access to the logs to diagnose it.

I'm more than happy to implement a solution myself, and I'm willing to use anything that is update-safe. I just don't know where the best place to start is.

Is there an established way in EspoCRM to intercept these types of exceptions/validation errors and present a user-friendly message without modifying the core?

[eymen-elkum]

This particular case does not seem to be a normal record-save validation error.

The request is:

POST /Invoice/{id}/validateEInvoice

The exception is coming from the e-invoicing library bundled with Sales Pack:

josemmo/einvoicing/src/Traits/PostalAddressTrait.php

For this endpoint, the cleanest solution would be to catch the library’s specific postal-address validation exception at the API-action boundary and convert it into an Espo HTTP exception with a user-friendly message.

Conceptually:

use Espo\Core\Exceptions\BadRequest;

try {
    // Validate or generate the e-invoice.
} catch (SpecificPostalAddressException $e) {
    throw new BadRequest(
        'The address cannot contain more than 3 lines. Please shorten the address and try again.'
    );
}

The exact exception class thrown by the library should be caught rather than catching every Throwable. This avoids hiding unexpected programming errors or exposing internal details to users.

Espo’s documented saveErrorHandlers mechanism is useful when an exception occurs during a normal record save. However, this request calls a custom validateEInvoice action, so a save-error handler probably won’t be invoked here.

A custom API middleware could also intercept exceptions without modifying the core, but I would not recommend a global interceptor for this single case. If middleware is used, it should target only this action and known validation exceptions.

Since the endpoint and e-invoicing library are part of the official Sales Pack, I recommend opening a support ticket through the official EspoCRM customer portal. Include the EspoCRM and Sales Pack versions, the complete log entry, the endpoint, and a reproducible example containing an address with more than three lines.

The best long-term fix would be for Sales Pack itself to convert these library validation exceptions into clear 4xx responses. This would provide meaningful feedback to every user and remain safe across upgrades.

For custom endpoints, applying the same exception-mapping pattern directly in the API action is the most maintainable approach.

[jamie]

THANK you for such a detailed and thoughtful explanation and guide, even if I don't do this, I learn more about espo

But as you say, the long-term fix is to update espo itself to do this

[jamie]

yuri i heard from a little bird that something like this is included in 10.0.7?

We are still on 9.3, as we are waiting for the fixes to calm down a bit

[yuri]

The problem with the particular library's exception is already fixed. RuntimeException are intended for internal errors which are not supposed to be caught. It was kind of misusing of the exception class in the library, hence it ended up unnoticed.

In v10.1 it will be possible to expose all exception messages to the frontend. But this parameter will be discouraged to be used on production because of security implications.

Basically all internal exception should be intercepted. Any Error 500 without any text other than "Check logs" should be treated as an internal error that should not happen. If it happen, either the vendor should fix the problem (we) or the administrator/developer of the system (if it's a customization or setup issue).