Magento 2 GraphQL Product Queries: Unraveling the 'Null Argument' Internal Server Error

At Shopping Mover, we constantly monitor the pulse of the Magento ecosystem, especially critical issues that impact store performance and developer experience. A recent GitHub issue (#41441) has brought to light a significant bug within Magento 2's GraphQL implementation concerning product queries, specifically when sort or filter arguments are explicitly passed as null.

This seemingly minor detail can lead to an 'Internal server error' for clients, breaking storefront functionality, particularly for modern PWA (Progressive Web App) frontends that frequently rely on GraphQL variables.

The Core Problem: GraphQL's Null Argument Mismatch

The issue, reported on Magento 2.4-develop, describes a scenario where GraphQL products queries fail when arguments like sort or filter are explicitly set to null. According to the GraphQL specification, passing an explicit null for a nullable argument should behave identically to omitting the argument entirely. For instance, sort: null should simply result in the default sort order, and filter: null should apply no filters.

However, Magento 2.4+ doesn't handle this as expected. Instead, requests like the following:

{ products(search: "bag", sort: null) { total_count } }

or

query($s: ProductAttributeSortInput) { products(search: "bag", sort: $s) { total_count } }

where $s is null, result in a generic 'Internal server error' for the client. The underlying debug message reveals a TypeError:

Magento\Framework\GraphQl\Query\Resolver\Argument\SearchCriteria\ArgumentApplier\Sort::applyArgument(): Argument #4 ($argument) must be of type array, null given, called in /app/code/Magento/CatalogGraphQl/DataProvider/Product/SearchCriteriaBuilder.php on line 91

This error occurs because Magento's SearchCriteriaBuilder::build() method iterates over all provided arguments without first checking if their values are null. When it encounters an explicit null for sort or filter, it attempts to pass this null value to methods like Sort::applyArgument() or Filter::applyArgument(). These methods, however, are strictly type-hinted to expect an array, leading to the fatal TypeError.

Impact on Magento Development and PWA Storefronts

This bug primarily affects developers and merchants utilizing Magento's GraphQL API, especially those building dynamic frontend experiences. PWA storefronts, for example, often use GraphQL variables to manage query parameters. If a variable intended for sort or filter is dynamically set to null (e.g., when no specific sort/filter is selected), it will trigger this error, leading to a broken user experience.

Interestingly, the issue highlights an inconsistency within Magento's GraphQL implementation: queries like categoryList(filters: null) and categories(filters: null) do not exhibit this failure, suggesting that their resolvers handle null arguments correctly. This discrepancy further complicates development and debugging efforts.

Community Response and Next Steps

The issue was identified from production error monitoring on live Magento stores, underscoring its real-world impact. It has been classified with a severity of S2, meaning it affects non-critical functionality but forces users to employ a workaround (which, in this case, involves ensuring null arguments are omitted rather than explicitly passed). The original reporter, lbajsarowicz, has commendably taken ownership of the issue, indicating that a fix is actively being worked on.

For Magento developers and merchants, staying informed about such critical bug fixes is paramount for maintaining stable and performant e-commerce platforms. As migration experts, we emphasize the importance of robust API behavior for seamless integrations and modern storefront development.