diff --git a/docs/guides/examples/vercel-sync-env-vars.mdx b/docs/guides/examples/vercel-sync-env-vars.mdx
index bcdb7d30cb7..f6c9a063e3d 100644
--- a/docs/guides/examples/vercel-sync-env-vars.mdx
+++ b/docs/guides/examples/vercel-sync-env-vars.mdx
@@ -6,9 +6,18 @@ description: "This example demonstrates how to sync environment variables from y
 
 import VercelDocsCards from "/snippets/vercel-docs-cards.mdx";
 
+<Warning>
+  **Deprecated when using the Vercel integration.** If you are using the [Vercel
+  integration](/vercel-integration), do not use `syncVercelEnvVars` — the integration handles env
+  var syncing natively and using both together can cause env vars to be incorrectly populated.
+
+  If you are **not** using the Vercel integration, `syncVercelEnvVars` is still supported. Continue
+  with the configuration below.
+</Warning>
+
 ## Build configuration
 
-To sync environment variables, you just need to add our build extension to your `trigger.config.ts` file. This extension will then automatically run every time you deploy your Trigger.dev project.
+If you are not using the [Vercel integration](/vercel-integration), you can sync environment variables manually by adding the `syncVercelEnvVars` build extension to your `trigger.config.ts` file. This extension will run automatically every time you deploy your Trigger.dev project.
 
 <Note>
   You need to set the `VERCEL_ACCESS_TOKEN` and `VERCEL_PROJECT_ID` environment variables, or pass
diff --git a/docs/vercel-integration.mdx b/docs/vercel-integration.mdx
index c5825d07140..a465f5aa39b 100644
--- a/docs/vercel-integration.mdx
+++ b/docs/vercel-integration.mdx
@@ -104,6 +104,12 @@ The following variables are excluded from the Vercel → Trigger.dev sync:
 
 You can control sync behavior per-variable from your project's Vercel settings. Deselecting a variable prevents its value from being updated during future syncs.
 
+<Warning>
+  If you are experiencing incorrectly populated environment variables, check that you are not using
+  the `syncVercelEnvVars` build extension in your `trigger.config.ts`. This extension is deprecated
+  and conflicts with the Vercel integration's built-in env var syncing. Remove it if present.
+</Warning>
+
 ### Supabase and Neon database branching
 
 If you use [Supabase Branching](https://supabase.com/docs/guides/deployment/branching) or [Neon Database Branching](https://neon.tech/docs/guides/branching-intro) for preview environments, disable syncing for database env vars on the Environment Variables page and use the [syncSupabaseEnvVars](/config/extensions/syncEnvVars#syncsupabaseenvvars) or [syncNeonEnvVars](/config/extensions/syncEnvVars#syncneonenvvars) build extensions instead. These extensions automatically resolve the correct branch-specific credentials at build time.