Handling migrations on local vs Vercel

[w3jerry]

Hello everyone,
I've spent the past 2 days trying to understand Payload's migrations and I couldn't seem to figure it out. Any help would be appreciated, or perhaps a paid-for consultation. Thank you in advance.

My current environments

Local

• Nextjs 15.1, Payloadcms 3.31.0 (all other plugins on the same version)
• Postgres database running in docker (push mode, so changes are reflected automagically)

Stage

• Deployed on Vercel
• Using postgres database from Supabase connected directly

Prod
In progress but will be:

• Deployed on Vercel
• Neon serverless postgres database

The problem

Developing on local environment works perfectly. I make a bunch of changes, they are handled by payload and it works nice and smooth. When I am done with local development, I create migrations via:
payload migrate:create -> This creates migrations which I then push into the desired branch

When deployed to Vercel, my ci pipeline starts:
payload migrate && pnpm build

Then, one of the two following issues happens:

1. I get a notification that I have run payload in development mode:
   ? It looks like you've run Payload in dev mode, meaning you've dynamically pushed changes to your database. and the build process gets stuck. - Since it's a build log, I can not interact with it.
2. I get a type error
   17:11:33.673] Types of property 'down' are incompatible. [17:11:33.673] Type 'typeof import("/vercel/path0/migrations/20250403_144756")' is not assignable to type '(args: MigrateDownArgs) => Promise<void>'. [17:11:33.673] Type 'typeof import("/vercel/path0/migrations/20250403_144756")' provides no match for the signature '(args: MigrateDownArgs): Promise<void>'.

Has anyone ever experienced this behavior or is it a misunderstanding on my end? Any help would be appreciated, I can share any additional files and information.

Thank you in advance for any help.

[grmilbrand]

I'm getting this same issue. The first build from 'Deploy' runs fine, I don't change anything in my git and trigger another build and it gives me:
INFO: Reading migration files from /vercel/path0/src/migrations
? It looks like you've run Payload in dev mode, meaning you've dynamically pushed changes to your database.

and hangs........
until it errors out after about 45 minutes!

[grmilbrand]

when I run npm payload migrate it gives me this error:
ERROR: Error running migration 20250515_125039 column "category_i_d" of relation "search_categories" already exists.

[w3jerry]

Yeah, so apparently you have to delete all the migrations from the payload_migrations table where the batch is "-1". Check if you got some, if so, try to delete them. It worked in my case. @grmilbrand

[grmilbrand]

! THAT WORKED !
Thank you so much! I don't know why that's not documented anywhere! (or how it happened)

[DanRibbens]

I think we need to delete the dev migration (batch -1) but I'm not sure where we should do that in the workflow. On migrate probably.

[w3jerry]

Yeah, I spent like a week on and off trying to figure this out. I use the default pipeline - payload migrate && pnpm build and just make sure I have all the correct migrations before I deploy the app. I assume that deleting the dev once during migrate is not a bad idea. Or if possible just include this info in the docs. If it fails on this error, there are dev migrations and a guide on how to delete them.

[grmilbrand]

The dev batch -1 shows up again every time I use ''NPM run dev'
If I run 'NPM run dev:prod', It doesn't show up. so I think I'll continue to do that