Android Studio warns that a VCS root mapping is invalid
Invalid VCS root mappingShort 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.
Fix it fast
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-toplevel2Match what you see, then jump to its fix
- 1
Entries in Directory Mappings are marked redA registered mapping points at a folder with no repositoryFix - 2
Rows shown in grey under Unregistered rootsThe repository is in a folder the IDE has not registeredFix - 3
git rev-parse prints: fatal: not a git repositoryThe project folder has never been put under GitFix
- 1
What does the error look like?
Invalid VCS root mappingDirectory 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 .git2Fix
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 Apply3Verify
Reopen Directory Mappings: no red rows remain and the warning does not return after a restart.
git statusConfirmed by jetbrains.com
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-toplevel2Fix
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 Add3Verify
The Git menu and the Git tool window appear for the project, and the row is no longer grey.
git log --oneline -n 3Confirmed by jetbrains.com
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 .git2Fix
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-toplevelConfirmed by git-scm.com
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
adb cannot start because something already holds its port
adb start-server failed
The adb server must bind local TCP port 5037, and every adb client talks to it there.
2 causes, each with a fixMobile apps
The phone shows as unauthorized and Android Studio will not run the app
adb devices lists the phone but Android Studio cannot deploy to it
An unauthorized phone means it has not trusted this computer's RSA key.
3 causes, each with a fixMobile 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 fixMobile apps
adb cannot connect to its daemon or start the server
* daemon started successfully *
The adb server is a background process on your computer that listens on TCP port 5037.
2 causes, each with a fixMobile apps
adb prints 'server version doesn't match this client; killing...'
adb server version doesn't match this client; killing...
adb runs a background server, and every adb command is a client.
3 causes, each with a fixMobile 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