How to fix the issue not a registered handle in Magento 2 admin grid

I recently added a custom grid in a custom module, like I’ve done hundreds of times before. The process I followed was identical to how I created my Magento 2 admin grids before, but this time I did something, or rather didn’t do something, because of which when I visited my grid page in the admin I got the following error message:

Not registered handle *_listing_data_source

At first I was not sure what the issue was, cause I was of the belief that I had done everything I used to do before and this wasn’t even a new Magento 2 version with breaking changes.

So what went wrong this time?

Note: This issue happens on UI component grid and if you are using the older method of creating the grid using PHP block, then this probably isn’t the article for you.

When you create an admin UI grid component, your ui_component/*_listing.xml file with the grid definition looks something like this:

<?xml version="1.0" ?>
<listing xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd">
    <argument name="data" xsi:type="array">
        <item name="js_config" xsi:type="array">
            <item name="provider" xsi:type="string">*_listing.*_listing_data_source</item>
        </item>
    </argument>
    <settings>
        ...
        <deps>
            <dep>*_listing.*_listing_data_source</dep>
        </deps>
    </settings>
    <dataSource component="Magento_Ui/js/grid/provider" name="*_listing_data_source">
        <settings>
            <updateUrl path="mui/index/render"/>
        </settings>
        <aclResource>{Namespace}_{Module}::{resource_id}</aclResource>
        <dataProvider class="Magento\Framework\View\Element\UiComponent\DataProvider\DataProvider" name="*_listing_data_source">
            <settings>
                <requestFieldName>id</requestFieldName>
                <primaryFieldName>id</primaryFieldName>
            </settings>
        </dataProvider>
    </dataSource>
    ...
</listing>

If you remember the older PHP version of the admin grids, it used to have method for preparing the collection from where the data was loaded into the grid. But in the case of XML, we can’t have a method to load the collection, which is why we define a dataSource.

dataSource is what loads the data from a certain place (most likely from your database table) into your Magento 2 admin grid. You can see in the above XML <dataSource>...</dataSource> which configures the data source for this grid. It has been given a unique name to identify the data source by it’s name. When this grid requests for *_listing_data_source, the data from that data source (a collection) is fetched and loaded into the table.

But if you noticed above, we haven’t defined a data source. We are just pointing to one that doesn’t exist. That is what caused the issue.

How to fix the issue?

To fix the issue, we need to define our data source. To do that, in the etc/di.xml of your module, add the following:

<virtualType name="{Namespace}\{Module}\Model\ResourceModel\{Model}\Grid\Collection" type="Magento\Framework\View\Element\UiComponent\DataProvider\SearchResult">
    <arguments>
        <argument name="mainTable" xsi:type="string">{your_table_name}</argument>
        <argument name="resourceModel" xsi:type="string">{Namespace}\{Module}\Model\ResourceModel\{Model}\Collection</argument>
    </arguments>
</virtualType>
<type name="Magento\Framework\View\Element\UiComponent\DataProvider\CollectionFactory">
    <arguments>
        <argument name="collections" xsi:type="array">
            <item name="*_listing_data_source" xsi:type="string">{Namespace}\{Module}\Model\ResourceModel\{Model}\Grid\Collection</item>
        </argument>
    </arguments>
</type>

Into the collections array property in the Magento\Framework\View\Element\UiComponent\DataProvider\CollectionFactory object, we add our data source with a unique identifier *_listing_data_source. This is the same identifier we used in the <dataSource>...</dataSource> settings in our ui_component/*_listing.xml.

And that’s it. We have fixed our issue. Reload your page after running the necessary commands, clearing cache etc., depending on the mode your on.