Vercel Error: gitBranch Can Only Be Used With target=preview

If Vercel returns an error like:

Environment Variables with gitBranch can only be used with target=preview.

the important clue is not the variable name.

It is the combination of gitBranch and target.

Vercel supports environment variables that apply only to a specific Git branch, but that branch-specific behavior belongs to the Preview environment. If you send a gitBranch together with a Production target, the configuration does not match Vercel's environment model.

The fix is usually simple:

If the variable is branch-specific, target Preview. If the variable is for Production, remove the Git branch scope.

Quick answer

For a branch-specific Preview variable, use:

vercel env add DATABASE_URL preview feature-branch

For a Production variable, use:

vercel env add DATABASE_URL production

Do not combine a Production target with a Git branch like this:

target = production
gitBranch = feature-branch

Vercel's current documentation says Preview environment variables can be applied to all non-production branches or to one specific branch. Branch-specific Preview values override the normal Preview value with the same name.

That is the model this error is enforcing.

Why this error happens

Vercel separates environment variables by deployment environment.

The standard environments are:

• Production — used by Production deployments
• Preview — used by non-production Git branches and Preview deployments
• Development — used for local development workflows

A Git branch such as:

feature-auth

normally produces a Preview deployment when it is not your Production Branch.

Vercel can therefore attach an environment variable specifically to that Preview branch.

For example:

DATABASE_URL
Preview
feature-auth

This means:

Use this value only when the Preview deployment comes from feature-auth.

That is different from a Production variable.

Production is already associated with the project's Production Branch. You configure the Production value for the Production environment itself rather than adding gitBranch to the variable.

The correct mental model

The easiest way I found to understand this is:

| What you want | Target | Git branch | | --- | --- | --- | | Same value for every Preview | Preview | None | | Different value for one feature branch | Preview | Specific branch | | Production value | Production | None | | Local development value | Development | None | | Extra release stage such as staging | Custom environment | Configure that environment intentionally |

The row that matters for this error is:

Specific Git branch → Preview

Vercel documents branch-specific environment variables as a Preview feature.

Correct CLI examples

Vercel's CLI supports this syntax:

vercel env add [name] [environment] [gitbranch]

The third argument is useful when the environment is Preview.

Add one value for all Preview deployments

vercel env add API_URL preview

This becomes the normal Preview value.

Override that value for one Preview branch

vercel env add API_URL preview feature-auth

Now deployments from feature-auth can use a different value.

Add a Production value

vercel env add API_URL production

There is no branch argument here.

That is the distinction that prevents the gitBranch / target=preview error.

The same rule applies when updating a variable

Vercel also supports branch-specific updates.

For example:

vercel env update API_URL preview feature-auth

But if the variable is a Production value, update the Production target without adding a Git branch:

vercel env update API_URL production

The principle is the same whether you are adding or updating:

Branch scope belongs to Preview.

If you are using the Vercel API or an integration

You can run into this error without typing a Vercel CLI command.

An integration, automation, SDK call, or API request may be creating an environment variable for you.

Conceptually, a problematic request looks like this:

{
  "key": "DATABASE_URL",
  "target": ["production"],
  "gitBranch": "feature-auth"
}

The request says two different things:

• make this a Production variable
• scope it to one Git branch

For a branch-specific Preview variable, the intent should instead look like:

{
  "key": "DATABASE_URL",
  "target": ["preview"],
  "gitBranch": "feature-auth"
}

For Production, remove the branch scope:

{
  "key": "DATABASE_URL",
  "target": ["production"]
}

The exact request shape can differ depending on the endpoint, SDK, or integration you are using, but the environment rule is the same.

Why branch-specific Preview variables are useful

Suppose your normal Preview deployments use:

DATABASE_URL=preview-database

Then one branch needs a separate database for an authentication experiment:

feature-auth

You can give only that branch a different value.

Vercel will combine the normal Preview variables with the branch-specific values. When the same variable exists in both places, the branch-specific value takes precedence.

That lets you override only what is different.

You do not need to duplicate every Preview environment variable for every branch.

How to check what Vercel has configured

Before changing application code, inspect the environment variables themselves.

List Preview variables

vercel env ls preview

List variables for a specific Preview branch

vercel env ls preview feature-auth

Pull Preview configuration locally

vercel env pull --environment=preview

Pull a branch-specific Preview configuration

vercel env pull --environment=preview --git-branch=feature-auth

Vercel also supports running a command with the branch-specific Preview environment without writing the values to a file:

vercel env run -e preview --git-branch feature-auth -- npm run dev

These commands help separate two questions:

1. Is the environment variable configured correctly in Vercel?
2. Does the application use it correctly?

Do not rewrite working application code until you know the answer to the first question.

What if I need a staging branch?

This is where the terminology can become confusing.

A branch named:

staging

is not automatically a special Vercel environment just because of its name.

If it is a non-production Git branch, it normally creates a Preview deployment and can use branch-specific Preview variables.

So this is valid for a Preview branch named staging:

vercel env add API_URL preview staging

If you want staging to be a true environment with its own lifecycle rather than just a Preview branch, Vercel also supports Custom Environments.

That is a different architecture decision.

Do not try to turn Production into a branch-specific environment by attaching gitBranch to a Production variable.

What if the branch is my Production Branch?

If your project's Production Branch is main, a push to main creates a Production deployment.

The Production environment variable should therefore be configured as Production:

vercel env add API_URL production

If you want a value only for a non-production branch, configure it as a Preview branch-specific variable instead.

The key distinction is the deployment environment, not merely the text of the branch name.

Branch-specific values override normal Preview values

This behavior is useful and easy to overlook.

Imagine you have:

API_URL = https://preview-api.example.com
Target = Preview

and also:

API_URL = https://auth-test-api.example.com
Target = Preview
Git branch = feature-auth

A normal Preview branch uses:

https://preview-api.example.com

The feature-auth Preview uses:

https://auth-test-api.example.com

Vercel's documentation explicitly describes branch-specific Preview values as overrides.

That is why this feature is useful for:

• testing another database
• pointing one branch to a test API
• trying a different authentication backend
• isolating a risky integration
• running a branch against temporary infrastructure

Do I need to redeploy after fixing it?

Yes.

Changing a Vercel environment variable does not modify deployments that already exist.

After correcting the target or branch scope:

1. save the environment variable
2. create a new Preview or Production deployment
3. confirm that the new deployment uses the expected environment
4. test the feature that depends on the variable

If you keep testing an old deployment, you can make the right configuration change and still think it failed.

Vercel's environment-variable documentation states that changes apply to new deployments rather than previous ones.

A practical troubleshooting sequence

When I see this error, I would check these in order:

1. What environment am I trying to configure? Preview or Production?

2. Did I include a Git branch? If yes, it should be a branch-specific Preview variable.

3. Is the target actually Preview? If not, either change it to Preview or remove the branch scope.

4. Does the branch really need a different value? If not, use one normal Preview variable instead.

5. Is an integration creating the variable? Check whether the integration is sending both gitBranch and a non-Preview target.

6. Did I create a new deployment after fixing it? Existing deployments keep their old environment configuration.

7. Am I testing the correct deployment? Verify the branch, commit, and deployment environment.

That sequence is faster than debugging the application itself.

Common mistakes

Setting a Production variable for a feature branch

A feature branch is normally a Preview deployment.

Use:

vercel env add VARIABLE_NAME preview feature-branch

not a Production variable with a branch attached.

Assuming every Preview branch needs its own full environment set

It does not.

Create general Preview variables first, then add branch-specific overrides only where the branch needs a different value.

Fixing the variable but testing the old deployment

Environment variable changes require a new deployment.

Confusing a Git branch with a Vercel environment

A branch is source-control context.

Preview, Production, Development, and Custom Environments are deployment environments.

They are related, but they are not the same concept.

Changing application code before checking the target

This error is about environment configuration.

Fix the environment model first.

Official Vercel references I checked

I verified this guide against Vercel's current documentation:

• Environment Variables — explains Production, Preview, Development, and branch-specific Preview variables.
• Managing environment variables across environments — shows the official branch-specific CLI example: vercel env add DATABASE_URL preview feature-branch.
• vercel env CLI reference — documents add, update, list, pull, and branch-specific Preview commands.

Those docs all point to the same rule:

A Git-branch-specific environment variable is a Preview configuration.

FAQ

What does “Environment Variables with gitBranch can only be used with target=preview” mean?

It means the environment-variable configuration includes a Git branch, but the requested target is not Preview. Branch-specific environment variables are designed for Preview deployments.

How do I create a branch-specific Vercel environment variable?

Use Preview plus the branch name:

vercel env add VARIABLE_NAME preview feature-branch

Can I use gitBranch with a Production environment variable?

Do not configure branch-specific Production variables this way. Set the Production variable for the Production environment without gitBranch.

Can one Preview branch override a normal Preview variable?

Yes. A branch-specific Preview variable with the same name overrides the general Preview value for that branch.

How do I verify the branch-specific variables locally?

You can pull them with:

vercel env pull --environment=preview --git-branch=feature-branch

or run a command with them using vercel env run.

Why is the old deployment still using the previous value?

Vercel environment-variable changes apply to new deployments. Redeploy after the configuration is corrected.

Final thought

The error looks technical, but the fix is mostly conceptual.

A Git branch is not another Production environment.

When you want one branch to use a different value, make it a branch-specific Preview variable.

When you want the live application to use a value, configure it for Production without the branch scope.

Once those two ideas are separated, the error becomes much easier to fix.

For the broader environment model, read Vercel Preview vs Production: Why Environment Variables Differ.

If your variables still exist but the deployed application cannot read them, continue with Vercel Environment Variables Not Working? 7 Fixes to Try.

If Vercel instead shows “Failed to verify the project’s public environment variable prefix”, use the public environment variable prefix troubleshooting guide.

Practical AI. Real Experience. Built in Public.