Exception handling

Exception Handling in Magento 2 GraphQL

In Magento 2, GraphQL exception handling is designed to protect sensitive information while still providing useful error messages to API clients. Magento uses different strategies depending on the type of exception and the current application mode (developer vs production).

How Magento Masks Exceptions

The WebApi module already provides an implementation to mask \Magento\Framework\Exception\LocalizedException messages so they are not fully exposed to external clients. GraphQL follows similar principles by:

Restricting verbose output to exceptions that implement \GraphQL\Error\ClientAware.
Only revealing detailed information when Magento is running in developer mode.
Returning a generic “Internal server error” message to the client in production mode.
Writing full exception details and stack traces to var/log/exception.log.

This approach ensures that end users do not see low-level technical details, while developers still have access to the information needed to debug issues.

Using `ClientAware` for GraphQL Errors

For GraphQL-specific logic in your custom modules, you should implement the \GraphQL\Error\ClientAware interface for exceptions that represent expected, user-facing errors (for example: validation errors, missing entities, or business-rule failures).

If you do not implement ClientAware, the client will only receive a generic error message, which makes debugging and UX worse. However, you must be careful to not apply ClientAware to too many exception types, as that may accidentally expose sensitive internal data.

        <?php
namespace Vendor\Module\Exception;

use GraphQL\Error\ClientAware;
use Magento\Framework\Exception\LocalizedException;

class InvalidInputException extends LocalizedException implements ClientAware
{
    /**
     * Return true if the error is safe to show to the client.
     */
    public function isClientSafe(): bool
    {
        return true;
    }

    /**
     * Optional: provide a custom category for the error.
     */
    public function getCategory(): string
    {
        return 'user';
    }
}
    

This exception can then be thrown from your resolver or service classes. When caught by Magento’s GraphQL layer, it will be surfaced to the client with a meaningful message instead of a generic internal error.

When Magento Returns Stack Traces

In developer mode, when an exception implementing ClientAware is thrown, Magento can return:

A detailed error message.
Extended debug information.
Stack trace details for easier troubleshooting.

In production mode, Magento suppresses these details for security reasons and logs them instead, while the client only receives a non-sensitive error message.

Core GraphQL Exception Classes

Magento provides a set of exception classes under:

Magento\Framework\GraphQl\Exception

These classes are specifically tailored for GraphQL behavior and typically already implement ClientAware, making them safe to expose to the client under the right conditions. They cover common GraphQL error scenarios such as:

Input validation failures.
Authorization and access control issues.
Entity not found or invalid resource errors.

When building custom resolvers, it is recommended to reuse these GraphQL-specific exception classes whenever possible, or extend from them, to maintain consistent error semantics across your API.

Best Practices for Exception Handling in Magento 2 GraphQL

Use ClientAware only for exceptions that are safe for clients.
Avoid exposing stack traces or internal identifiers in production.
Always log full exception details to help with debugging.
Use LocalizedException for user-facing errors that may also appear in other areas of Magento.
Prefer Magento’s built-in Magento\Framework\GraphQl\Exception classes for common scenarios.

By following these practices and leveraging the GraphQL exception handling infrastructure correctly, you can provide clear, meaningful error messages to clients while keeping your Magento 2 store secure and maintainable.

Exception handling

Exception handling