How to fix error: cannot run merge driver 'driver-name' in Git

GitINTERMEDIATEMEDIUM

Git cannot execute a custom merge driver specified in .gitattributes. This happens when the driver is referenced but not properly configured in your Git config, or when the driver command is unavailable.

What this error means

This error occurs when Git attempts to use a custom merge driver defined in your `.gitattributes` file but cannot execute it. Merge drivers are custom programs that handle how Git merges conflicting changes in specific files. While you can reference a merge driver in `.gitattributes`, Git requires the actual driver implementation to be defined in your Git configuration (`.git/config` or global config). The error indicates a disconnect between your `.gitattributes` declaration (which specifies WHICH files should use the driver) and your Git config (which specifies HOW the driver works). This is a common configuration issue because merge driver configurations cannot be committed to the repository—each developer must set them up locally. Custom merge drivers are powerful tools for handling special file types (like generated files, lock files, or binary formats) but require careful setup on every machine that will perform merges.

How to fix "error: cannot run merge driver 'driver-name'"

1Check your .gitattributes configuration

First, verify which merge driver is referenced in your .gitattributes file:

bash

cat .gitattributes

Look for lines like:

bash

*.json merge=custom-json-driver
package-lock.json merge=ours

Note the driver name (the part after merge=). You'll need this for the next steps.

2Verify the driver is defined in Git config

Check if the merge driver is configured locally or globally:

bash

# Check local config
git config --local --get-regexp merge

# Check global config
git config --global --get-regexp merge

You should see entries like:

bash

merge.custom-json-driver.name A custom JSON merge driver
merge.custom-json-driver.driver /path/to/merge-script.sh %O %A %B

If nothing appears, the driver is not configured.

3Define the merge driver in Git config

If the driver is missing, add it to your Git config. For a simple "ours" strategy (keep current branch version):

bash

git config --global merge.ours.driver true

For a custom script-based driver:

bash

git config --global merge.custom-driver.name "My custom merge driver"
git config --global merge.custom-driver.driver "/usr/local/bin/my-merge-tool.sh %O %A %B"

Placeholders:
- %O = base/ancestor version
- %A = current branch version (result should be written here)
- %B = other branch version
- %L = conflict marker size
- %P = file pathname

4Ensure the driver script is executable and in PATH

If using a custom script, verify it exists and is executable:

bash

# Check if script exists
ls -la /usr/local/bin/my-merge-tool.sh

# Make executable if needed
chmod +x /usr/local/bin/my-merge-tool.sh

# Test the script manually
/usr/local/bin/my-merge-tool.sh test1.txt test2.txt test3.txt

If the script is not in an absolute path, ensure it's in your PATH:

bash

echo $PATH
which my-merge-tool.sh

5Verify the script writes output to the correct location

Custom merge drivers must write the final merged result to the file specified by %A (current version). Ensure your script:

1. Reads all three input files (%O, %A, %B)
2. Performs merge logic
3. Writes the result to %A
4. Exits with code 0 for success, non-zero for failure

Example minimal script:

bash

#!/bin/bash
# Simple "ours" merge: keep current version
BASE=$1
OURS=$2
THEIRS=$3

# Result already in $OURS, just exit successfully
exit 0

6Retry the merge operation

After configuring the driver, retry your merge:

bash

# If merge was in progress
git merge --continue

# Or start a fresh merge
git merge <branch-name>

# Or pull with merge
git pull origin main

Git should now successfully invoke your custom merge driver for the specified files.

7Remove the custom driver if no longer needed

If you don't actually need the custom merge driver, you can either:

Option 1: Remove the driver reference from .gitattributes:

bash

# Edit .gitattributes and remove or comment out the merge= line
git add .gitattributes
git commit -m "Remove custom merge driver requirement"

Option 2: Use a built-in driver:

bash

# In .gitattributes, use built-in drivers
*.json merge=union      # Combine both sides
*.lock merge=ours       # Always keep our version
*.gen merge=theirs      # Always keep their version

Advanced notes

Why merge drivers can't be committed: Git config settings (where merge drivers are defined) are local to each machine and cannot be committed to the repository for security reasons. Malicious actors could otherwise force arbitrary code execution on every clone. Teams using custom merge drivers should document setup in README files or provide installation scripts.

Difference between high-level and low-level conflicts: Custom merge drivers only handle low-level (content) conflicts. If you encounter a high-level conflict (e.g., one branch deleted a file while another modified it), Git will not invoke your merge driver and will use its standard conflict resolution.

GitHub and custom merge drivers: GitHub's web interface does not support custom merge drivers. Merges performed via GitHub pull requests will use GitHub's default merge strategy, regardless of your .gitattributes settings. Custom drivers only work for local Git operations.

Windows line ending issues: If your merge driver outputs files with Windows line endings (\r\n) but Git expects Unix line endings (\n), you may get unexpected errors. Ensure your driver respects the repository's line ending configuration or outputs Unix-style endings.

Driver exit codes: Exit code 0 indicates success (merge completed). Exit codes 1-127 indicate failure but Git will mark the file as conflicted and allow manual resolution. Exit codes >128 indicate the driver crashed (e.g., SIGSEGV), which causes the entire merge to fail.

Testing merge drivers: You can test merge drivers outside of actual merges by manually invoking them with test files:

bash

/path/to/driver.sh base.txt current.txt incoming.txt
echo $?  # Should be 0 on success

Distribution strategies: For teams, consider:
1. Providing a setup script that configures the driver for new contributors
2. Using Git hooks to verify driver configuration
3. Including driver scripts in a tools/ directory in the repository
4. Documenting the driver setup prominently in CONTRIBUTING.md

How to fix error: cannot run merge driver 'driver-name' in Git

What this error means

Typical symptoms

Common causes

How to fix "error: cannot run merge driver 'driver-name'"

Advanced notes

Related errors

Official resources & further reading