In this article, I'll show you the cause of the following error and how to fix it.

ERROR [root] Error: Multiple head revisions are present for given argument 'head'; 
    please specify a specific target revision, '<branchname>@head' to narrow 
    to a specific head, or 'heads' for all heads

This error will showup whenever you run Flask Migrate upgrade migration command using

(venv) $ flask db upgrade

Flask Migrate is an extension that handles SQLAlchemy database migrations for Flask applications using Alembic

We'll demystify when this error will occur with an example scenario. Let the initial migraion state be

* C (head)
| 
* B
|
* A

Say, two developers create a migration branches from C

* F
|
| * E
| | 
| * D
|/ 
* C (head)
| 
* B
|
* A

One developer pushes F to become new head

* F (head)
|
| * E (head)
| | 
| * D
|/ 
* C
| 
* B
|
* A

Now if another developer merges the changes and run flask db upgrade will end up having the above ERROR.

This inconsistency state can be identified using the command

(venv) $ flask db history

To see the following output, where we can see it clearly there are two head revisions present.

D -> E (head), empty message
C -> D, empty message
C -> F (head), empty message
B -> C (branchpoint), empty message
A -> B, empty message
<base> -> A, empty message

Now, you can manually resolve this conflict by modifying the down_revision or using the following command

(venv) $ flask db merge heads -m "merging two heads"

You can even explicitly mention which two heads you wanted to merge like

(venv) $ flask db merge D F -m "merging D and F"

Hope this helps!