Start Building
Programming & Scripting Errors Mar 7, 2026

Unity Version Control Integration Broken - Git/Perforce Fix

Unity version control (Git or Perforce) not working? Fix broken integration, lock files, and collaboration issues with this step-by-step troubleshooting guide.

By GamineAI Team

Unity Version Control Integration Broken - Git/Perforce Fix

Problem Statement

Unity's version control integration (Git or Perforce) has stopped working. You may see errors when committing, pulling, or pushing; the Version Control window may be missing or grayed out; or team members may get lock conflicts or merge errors when working in the same project.

Common symptoms:

  • Version Control menu or window is missing or disabled
  • Git/Perforce operations fail with "not a repository" or "connection refused"
  • Lock files (.meta conflicts, .unity conflict markers) after pull or merge
  • "Visible Meta Files" or "Force Text" not applied and scenes merge badly
  • Plastic SCM or other provider appears instead of Git/Perforce
  • Collaborators cannot sync or get "asset is locked" errors

Root Cause Explanation

Version control breaks in Unity for several reasons:

  • Project not under version control – Folder is not a Git repo or not connected to Perforce
  • Wrong serialization mode – Binary or "Mixed" serialization causes merge conflicts; Unity recommends Force Text for Git
  • Meta file visibility – If "Visible Meta Files" is off, .meta GUIDs can get out of sync across machines
  • Editor cache or state – Version Control package or Editor prefs can be corrupted
  • Permissions or path – Long paths, special characters, or read-only folders can block Git/Perforce
  • Package or Unity version mismatch – Different Unity or VC package versions between team members

This guide walks you through fixes for both Git and Perforce so you can restore integration and collaborate safely.

Quick Fixes (Try These First)

1. Enable Version Control and Set Correct Mode (Git)

If you use Git, Unity must be configured for it and for merge-friendly serialization.

Steps:

  1. Open Edit → Project Settings → Editor
  2. Under Version Control, set Mode to Visible Meta Files
  3. Under Asset Serialization, set Mode to Force Text
  4. Click Apply
  5. Restart Unity if the Version Control window still does not appear

Verification: After restart, Window → General → Version Control (or Team in some versions) should be available. Your project folder should already be a Git repo (git init or clone done outside Unity).

Pro tip: Force Text and Visible Meta Files are recommended in Unity's official Git setup. If your project was created with Binary serialization, switch to Force Text and commit the re-serialized assets once so the team is in sync.

2. Reconnect Perforce Workspace

If you use Perforce and Unity no longer sees it:

Steps:

  1. Open Window → General → Version Control (or Version Control from the menu)
  2. If the window shows "Connect" or "Not connected," click it
  3. Enter your Perforce server, user, workspace, and password/depot path as required
  4. Ensure the project path matches your Perforce workspace root (where your Unity project lives)
  5. Click Connect and wait for Unity to refresh

Verification: The Version Control window should show your workspace and pending changes. If connection still fails, check Perforce server URL, firewall, and that P4V or command-line p4 works in the same folder.

Alternative: Some teams use the Plastic SCM (Unity Version Control) package. If you intend to use Git or external Perforce, disable or remove the Plastic package so it does not take over.

3. Fix Lock Files and Merge Conflicts

After a pull or merge, Unity may report conflicted or locked assets.

Steps:

  1. In your Git client (e.g. GitHub Desktop, SourceTree, or command line), resolve text conflicts in .unity and .prefab files. Search for <<<<<<<, =======, >>>>>>> and keep the correct block (or merge by hand)
  2. For .meta files, ensure each asset has exactly one .meta and that the GUID inside is consistent. If two .meta files exist for the same asset, delete the duplicate and keep the one that matches the asset's GUID in the main repo
  3. In Unity, reimport affected folders: right-click folder in Project → Reimport
  4. If Unity reports "script or asset missing," fix any broken script references (e.g. missing script on a prefab) and re-save the scene/prefab

Verification: Open the scene or prefab; no "Missing Script" or duplicate asset errors. Commit the resolved files.

Pro tip: To avoid merge hell, the whole team should use Force Text and Visible Meta Files. Add a note in your repo README so new members set this before first pull.

4. Restore Version Control Package (Unity 2020+)

If the Version Control window is missing and you use the built-in Git support:

Steps:

  1. Open Window → Package Manager
  2. Switch the top-left dropdown to Unity Registry
  3. Search for Version Control or Git
  4. If Version Control is listed, select it and click Enable or Install
  5. If it is already installed, try Remove, then Install again
  6. Restart Unity

Verification: Window → General → Version Control (or Team) appears and shows your repo status.

Note: Unity’s Git integration has evolved by version. If your Unity release does not include a Git package, use an external client (e.g. Git GUI, GitHub Desktop) and keep Unity’s serialization settings as above so that merges stay manageable.

5. Clear Editor Prefs and Caches (Last Resort)

If integration is still broken and no other fix worked, reset Unity’s version-control-related state.

Steps:

  1. Close Unity
  2. Delete or rename the Library folder inside your project (Unity will regenerate it; this can take a few minutes)
  3. Optionally clear EditorPrefs: delete or rename EditorPrefs under your OS user folder (see Unity’s documentation for paths). This affects all Unity projects, so only do this if you are comfortable resetting editor preferences
  4. Reopen the project and reconfigure Version Control and Asset Serialization as in step 1

Verification: Version Control reconnects and shows correct status. Re-import may take a while on first open.

Prevention Tips

  • Document settings: In your repo README, state: "Unity: Force Text, Visible Meta Files. Required for Git."
  • .gitignore: Use a Unity .gitignore so Library, Temp, and user-specific files are not committed.
  • Same Unity version: Align the team on the same Unity editor version (and VC package if used) to avoid compatibility issues.
  • Small, frequent commits: Commit and push often so merges stay small and conflicts are easier to resolve.
  • Perforce: Keep workspace and stream paths consistent; avoid mixing different Perforce servers or workspaces for the same project.

When to Seek More Help

  • Perforce: If the server is managed by your studio, ask your build/IT team for the correct server URL, workspace name, and permissions.
  • Git LFS: If you use Git LFS for large assets and see "pointer" or "LFS" errors, ensure Git LFS is installed and run git lfs install and git lfs pull as needed. See Git LFS documentation.
  • Unity Cloud / Plastic: If your team uses Unity Version Control (Plastic), follow Unity’s Plastic SCM docs for that workflow instead of external Git/Perforce.

Related Help and Guides

Bookmark this article for quick reference when version control acts up. If this fix helped, share it with your team so everyone uses the same Unity and VC settings. For more on project setup and collaboration, see our Unity guides and courses.

FAQ

Do I have to use Force Text for Git?
Unity recommends it for Git so that .unity and .prefab files merge as text. Binary serialization makes merges almost impossible. Switch once and have the whole team commit the re-serialized assets.

Unity shows Plastic SCM but we use Git. What do I do?
Disable or remove the Plastic SCM (Unity Version Control) package in Package Manager so it does not override. Use an external Git client and keep Force Text + Visible Meta Files in Project Settings.

Perforce connection works in P4V but not in Unity.
Confirm the project path in Unity’s Version Control window matches your Perforce workspace root. Check that the same user and workspace are used. Restart Unity after changing the connection.

We get .meta conflicts every time we merge.
Ensure every machine uses Visible Meta Files and Force Text. If someone committed with "Hidden Meta Files," their .meta GUIDs can differ and cause conflicts. Re-sync to one mode and document it in the README.