Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

Android Studio warns that a VCS root mapping is invalid

ErrorInvalid VCS root mapping

Short answer

The IDE keeps a list of folders it treats as version control roots. The warning appears when an entry points at a folder with no repository in it. Open Settings > Version Control > Directory Mappings, remove the red entries, then add the folder that really holds your .git directory. If no repository exists yet, create one.

  • Applies to Android Studio current stable, Git 2.4x, macOS 26, Windows 11
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out where the repository really is. Run this from the project folder. It prints the top level of the repository, or an error if none exists above this folder.

    git rev-parse --show-toplevel
  2. 2Match what you see, then jump to its fix

    1. 1Entries in Directory Mappings are marked redA registered mapping points at a folder with no repositoryFix
    2. 2Rows shown in grey under Unregistered rootsThe repository is in a folder the IDE has not registeredFix
    3. 3git rev-parse prints: fatal: not a git repositoryThe project folder has never been put under GitFix

What does the error look like?

  • Invalid VCS root mapping
  • Directory Mappings lists registered roots in red

Cause 1 of 3

A registered mapping points at a folder with no repository

1Check

In Settings, open Version Control > Directory Mappings. The IDE checks each registered root and marks invalid ones in red. The page describes this as a repository that does not exist at the specified path, for example after the folder was moved or deleted.

ls -a path/to/the/red/folder | grep -x .git

2Fix

Select each red entry and use the remove button (the minus), then apply the change.

# no command: Settings > Version Control > Directory Mappings
# select the red row, click the minus button, click Apply

3Verify

Reopen Directory Mappings: no red rows remain and the warning does not return after a restart.

git status

Confirmed by jetbrains.com

Did this fix it?

Cause 2 of 3

The repository is in a folder the IDE has not registered

1Check

Git and Mercurial repositories the IDE finds but does not manage are listed under Unregistered roots in grey. The git command above works, yet the IDE shows no Git tools for that folder.

git rev-parse --show-toplevel

2Fix

Select the grey row and click Add so the IDE registers it. For a project with more than one version control system, the page tells you to choose the Project entry instead of one directory.

# no command: Settings > Version Control > Directory Mappings
# select the row under Unregistered roots, click Add

3Verify

The Git menu and the Git tool window appear for the project, and the row is no longer grey.

git log --oneline -n 3

Confirmed by jetbrains.com

Did this fix it?

Cause 3 of 3

The project folder has never been put under Git

1Check

No .git directory exists in the project folder or in any parent of it.

ls -a | grep -x .git

2Fix

Create the repository with git init, or in the IDE use VCS > Enable Version Control Integration and choose Git. git init is safe in an existing folder: it does not touch the files already there.

git init
git add .
git commit -m "Initial commit"

3Verify

Run the first-step command again. It prints the project folder path.

git rev-parse --show-toplevel

Confirmed by git-scm.com

Did this fix it?

How do I stop it coming back?

  • After moving a project folder, open Directory Mappings once and remove entries that point at the old path.
  • Keep one repository at the project root instead of nesting several repositories inside one project.
  • Clone through the IDE when you can: it registers the root mapping for you.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Mobile apps

Android Studio cannot pair the phone over Wi-Fi

The Pair devices over Wi-Fi dialog lists no device

Wireless pairing needs the phone on Android 11 or higher and on the same Wi-Fi network as the computer, with current Platform-Tools.

4 causes, each with a fix

Mobile apps

adb tcpip 5555 fails because no device is found

adb: more than one device/emulator

adb tcpip only works while the device is attached and listed by adb, because it tells the phone to start listening on port 5555.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.