UnityYAMLMerge Troubleshooting

UnityYAMLMerge Error Reference: Not Found, Not Working, Expected Key

UnityYAMLMerge failures usually fall into three groups: Git cannot find or execute the tool, Git does not route the Unity file to the configured driver, or UnityYAMLMerge cannot parse one of the input files. Diagnose those layers in order and preserve every merge input before retrying.

7 Wolves July 29, 2026 10 min read Troubleshooting

Error: UnityYAMLMerge not found

UnityYAMLMerge ships inside each Unity Editor installation. Common default locations are:

# macOS
/Applications/Unity/Hub/Editor/<version>/Unity.app/Contents/Tools/UnityYAMLMerge

# Windows
C:\Program Files\Unity\Hub\Editor\<version>\Editor\Data\Tools\UnityYAMLMerge.exe

# Linux
~/Unity/Hub/Editor/<version>/Editor/Data/Tools/UnityYAMLMerge

Confirm the exact installed version and executable path. Quote paths containing spaces. Avoid a team configuration that assumes every workstation installs Unity in the same location.

git config --get merge.unityyamlmerge.driver
git config --show-origin --get merge.unityyamlmerge.driver

Git does not run UnityYAMLMerge

Check both halves of the configuration:

.gitattributes must match the path and name the intended merge driver.
Git config must define merge.<name>.driver with that exact name.

git check-attr merge -- Assets/Scenes/World.unity
git config --get-regexp '^merge\.'

If the attribute is unspecified, the pattern is missing, not committed, overridden later, or does not match the asset path. If the attribute names a driver but Git config lacks that driver, the local setup is incomplete.

The driver runs but does not resolve the file

Confirm that Asset Serialization is Force Text.
Verify the expected argument order for ancestor, incoming, current, and output paths.
Check quoting around executable and temporary file paths.
Run the command from a shell and inspect its exit code and stderr.
Confirm that the tool can write the expected result path.
Remember that a non-zero result can correctly mean unresolved conflicts remain.

UnityYAMLMerge is not required to solve every semantic conflict. Both-edited values, structural overlap, unsupported assets, or malformed YAML can legitimately remain unresolved.

Error: did not find expected key

This message means at least one merge input could not be parsed as the Unity YAML shape expected by the tool. Common causes include unresolved conflict markers, truncated files, manual edits that break indentation or mapping structure, unsupported serialized content, or a tool-specific parser limitation.

Unity issue UUM-65675 documents a reproducible did not find expected key case caused by a # symbol in the target file for the tested UnityYAMLMerge versions. That specific issue does not mean every # is the cause; inspect the exact file and line reported.

Copy Base, Ours, Theirs, and any premerged output to a recovery directory.
Search all inputs for Git conflict markers.
Open the reported file near the parser line and compare it with the last valid revision.
Test each contributor independently to identify the failing side.
Retry with the UnityYAMLMerge binary from the project's Unity version.
If the shape is unsupported, resolve with explicit Unity-domain review instead of forcing the parser.

Use a transparent fallback

When an automatic result is unclear, MergeSight structured Unity conflict inspection can build a semantic Base / Ours / Theirs model, classify unresolved decisions, show raw YAML alongside Unity structure, preview the result, and fail closed on unsupported or ambiguous states.

This does not guarantee that malformed input can be recovered automatically. It gives the team explicit evidence and avoids treating a black-box exit as the final decision.

Diagnostic table

Symptom	First check	Likely layer
Command not found	Installed Unity path and quoting	Executable discovery
Git uses normal text merge	`git check-attr merge`	Attributes
Named driver missing	`git config --get-regexp '^merge\.'`	Local Git config
Non-zero with unresolved file	stderr and remaining decisions	Legitimate conflict or invocation
Expected key	Exact failing input and line	YAML content or parser limitation

Verify after the fix

Run a disposable conflict using the same Unity version, Git config, and attribute rules as the team. Confirm that clean cases return success, unresolved cases remain visible, the output contains no markers, and the resulting scene or prefab opens and validates in Unity.

FAQ

Where is UnityYAMLMerge installed?

It is inside each Unity Editor installation. The exact path differs by operating system, Unity version, and installation location.

Why is Git not using UnityYAMLMerge?

The .gitattributes path may not match, the merge driver name may differ from Git config, the attributes file may not be tracked, or a later rule may override it.

What does did not find expected key mean in UnityYAMLMerge?

One input could not be parsed as expected Unity YAML. Check conflict markers, truncation, indentation, manual edits, unsupported content, the reported line, and known parser limitations.

Does a non-zero UnityYAMLMerge exit mean the setup is broken?

Not always. A non-zero exit can correctly report that unsafe or unresolved conflicts remain. Inspect stderr, output files, and the active Git conflict state.

Summary

Check discovery

Verify the installed executable, version, path, permissions, and quoting.

Check routing

Confirm the effective merge attribute and the matching local Git driver.

Check every input

Preserve and test Base, Ours, Theirs, and output when parsing fails.

Troubleshooting is fastest when executable discovery, Git routing, command invocation, and Unity YAML parsing are treated as separate layers.

Next step

For complete Git configuration examples, use the UnityYAMLMerge guide for Git, scenes, and prefabs.