Debugging Magento composer patch errors: wrong path, wrong type

Applying custom patches in Magento 2 via cweagans/composer-patches is straightforward until it isn’t. When it fails, the error message often points at the patches library rather than your configuration, which sends people down the wrong path.

The most common failure looks like this:

[TypeError]
Composer\Util\RemoteFilesystem::copy(): Argument #1 ($originUrl) must be
of type string, null given, called in
/var/www/html/vendor/cweagans/composer-patches/src/Patches.php on line 388

This error comes from cweagans/composer-patches receiving a null where it expects a string. The null is your patch file path. Your composer.json has an incorrect path — either a typo, a wrong directory name, or the file genuinely doesn’t exist at the location you specified.

The typical cause

In your composer.json, patch registration looks like this:

"extra": {
    "patches": {
        "magento/magento2-base": {
            "Fix setup upgrade trigger ordering": "patches/magento/magento2-base/fix-trigger-order.patch"
        }
    }
}

The string value on the right is the path to your patch file, relative to the composer.json root. If there’s a typo anywhere in that path — wrong directory name, wrong file extension, extra space — the patches library can’t resolve it to a real file, receives null from the path resolution, and throws the type error.

A real example I’ve seen: Modle/Rule/Condition/Customer.patch instead of Model/Rule/Condition/Customer.patch. The directory was Model. The path said Modle. The error message gave no indication of what the typo was.

Debugging it

Check the actual path first:

ls -la patches/magento/magento2-base/

If the file isn’t there, create it or fix the path. If the file is there, compare the path in composer.json character by character against the actual filesystem path. Directory names on Linux are case-sensitive — Model and model are different directories.

If the file exists and the path is correct, verify the file has the right line endings. A patch file created on Windows and committed with CRLF line endings will fail to apply on Linux. Convert with:

dos2unix patches/your-patch-file.patch

Writing the patch file correctly

A valid unified diff patch for Magento core:

--- a/setup/src/Magento/Setup/Console/Command/UpgradeCommand.php
+++ b/setup/src/Magento/Setup/Console/Command/UpgradeCommand.php
@@ -142,8 +142,8 @@
         $this->cache->clean();
         $searchConfig->validateSearchEngine();
-        $installer->removeUnusedTriggers();
         $installer->installSchema($request);
+        $installer->removeUnusedTriggers();
         $installer->installDataFixtures($request, true);

The --- and +++ paths should be relative to the package root, not the Magento root. For magento/magento2-base, the files live at setup/src/... within the package — not at vendor/magento/magento2-base/setup/src/....

On Adobe Commerce Cloud

Adobe Commerce Cloud uses ece-tools for patch management rather than cweagans/composer-patches. Patches are placed in the m2-hotfixes directory at the Magento root, not registered in composer.json. The patch file format is the same unified diff, but the registration mechanism is different. If you’re applying this on a Cloud project and the above doesn’t apply to your setup, check your project’s ece-tools documentation for the correct patch directory.

Prevention

The easiest way to prevent this class of error: after adding a new patch entry to composer.json, immediately run composer validate and then ls the path you just typed. Two seconds of verification saves twenty minutes of debugging a misleading error message.