My Vercel deploys were BLOCKED because of the commit author email

There was a problem that consumed a full day while I was building this site. Pushing to GitHub was supposed to trigger automatic deployment on Vercel, but it did not deploy. More precisely, deployments were created, but their status was BLOCKED.

Deploying directly through the CLI produced the same result. And when I listed deployments with vercel ls, the status appeared as UNKNOWN, which gave me no clue what was wrong.

Everything I suspected was wrong

I investigated these in order.

1. The Root Directory setting. This repository has its Next.js app inside web/. I thought the project’s Root Directory might not have been set to web. It was correctly configured.
2. GitHub App permissions. I wondered whether Vercel’s GitHub integration lacked access to this repository. I even reconnected it. It was unrelated.
3. Exceeded free-plan usage. I wondered whether I had exceeded the Hobby plan’s deployment count or build time. I had not.
4. A build failure. This was not it either. BLOCKED occurs before the build starts. There are no logs at all.

Checking all four took time. The problem was that the cause appeared nowhere. The dashboard said only that the deployment was blocked, not why.

The API showed the exact cause

I queried the deployment list directly through the Vercel REST API.

GET /v6/deployments?projectId=...

Each deployment object has an errorMessage field and a seatBlock.blockCode field. They said this.

TEAM_ACCESS_REQUIRED
Git author <email> must have access to the team

Vercel allows deployment only when the commit author’s email belongs to a Vercel team member.

My situation was this. The repository’s commit author email was A. The Vercel Hobby team had only B as a member. Both emails belonged to me, but Vercel knew only B.

That is why Git’s automatic deployments and CLI deployments were blocked in exactly the same way. CLI deployment also refers to the commit in the end.

The fix

I changed the commit author to the team member email in the repository’s local configuration.

git config user.email "<email-of-a-vercel-team-member>"

I used repository-local configuration rather than global configuration. I wanted to leave the commit identity for other projects unchanged.

Then I committed and pushed. It became READY in 35 seconds. The deployment source also correctly showed git.

There is another option. Add and verify another email in the account settings of the Vercel dashboard, and that author will pass too. This is better in some cases. It leaves the commit identity unchanged, so I would use it for a project whose commit log needs to retain the original email.

Because this was a personal site, I chose the simpler route. I left a note in the repository instead. This repository’s commit author must use a team member email for automatic deployment to continue working. Without that note, I would run into the same problem again a few months later.

A side discovery: Root Directory and the CLI deployment path

I learned something else during the same detour.

When a project’s Root Directory is set to web, the CLI deployment command must run from the repository root, not inside web/. Vercel reads the configuration from the root, then finds web within it. Running it inside web/ doubles the path.

The error message for this was not helpful either, so I spent a long time on it.

Rules I kept from this detour

First, I do not trust UNKNOWN from vercel ls. When the status is unknown, I call the API directly rather than relying on the CLI. The cause appears as a string in errorMessage and blockCode.

Second, I do not assume a deployment failure is a build problem first. When there are no build logs, it was blocked before the build stage, usually by permissions or identity. A failure with logs and one without logs are entirely different kinds of problems.

Third, a platform can use commit metadata for access control. I had thought of the commit author email as a label. In practice, it was an access-control input. When CI or deployment blocks without explanation, I add the commit author and committer to the checklist.

The question that stays

Most of the time I spent solving this problem went into finding the cause. The fix itself was one command.

And the cause had been in the API response as a string from the beginning. The dashboard simply did not show it.

A status summarized by a UI is not diagnostic information. In making it easier for people to read, the process discards the cause. So when something blocks, I should not click further through the UI. I should inspect the original data the UI reads.

The question to ask is this. Which API response is this screen summarizing? Once I know that, most deployment detours shrink to a few minutes.

These observations are from the Hobby plan in late June 2026. Platform behavior may change.