"vercel pull" fails when using project-scoped token, "Error: Could not retrieve Project Settings"
Author: raxod502Created Aug 15, 2026Updated Sep 16, 2026
vercel pull is nonfunctional when using a project-scoped token. It only works when using a team-scoped token. This makes little sense, since the command is acting on a single project and should only require a project-scoped token to retrieve settings for that project.
https://github.com/vercel/vercel/issues/10874 is about the same error message, and correctly points out that the error message is bad. However, this issue is separate and reports the fact that the command should not be failing in the first place.
Frankly, I'm at a loss for how to properly configure GitHub Actions to deploy to Vercel, with this bug. As far as I'm aware, running vercel pull is what you're supposed to do (followed by vercel build, vercel deploy), but if it doesn't work when using a project-scoped token, then every individual repository ends up getting deploy access to every single project, which is just terrible from a security point of view.
Error trace, when using a project-scoped token:
% VERCEL_ORG_ID=team_xxx VERCEL_PROJECT_ID=prj_xxx npx vercel pull --token=xxx --debug
> [debug] [2026-08-15T21:21:26.834Z] Found config in file "/path/to/project/vercel.json"
Vercel CLI 59.1.3 (Node.js 26.4.0)
> [debug] [2026-08-15T21:21:26.852Z] Agent/TTY/nonInteractive: isAgent=false agentName=none stdin.isTTY=true --non-interactive=false explicitFalse=false => nonInteractive=false
> [debug] [2026-08-15T21:21:26.852Z] user supplied known subcommand: "pull"
> [debug] [2026-08-15T21:21:27.007Z] Using token from `--token` argument, skipping token refresh.
> [debug] [2026-08-15T21:21:27.020Z] #1 → GET https://api.vercel.com/v2/user
> [debug] [2026-08-15T21:21:27.031Z] Spinner invoked (Retrieving project…) with a 1000ms delay
> [debug] [2026-08-15T21:21:27.033Z] #2 → GET https://api.vercel.com/teams/team_xxx
> [debug] [2026-08-15T21:21:27.034Z] #3 → GET https://api.vercel.com/v9/projects/prj_xxx?teamId=team_xxx
> [debug] [2026-08-15T21:21:27.137Z] #1 ← 404 : sfo1::9llvg-1786828887035-91126d50f18f [117ms]
> [debug] [2026-08-15T21:21:27.145Z] #2 ← 403 : sfo1::cxtsl-1786828887045-76a61a3a46f3 [112ms]
> [debug] [2026-08-15T21:21:27.246Z] #3 ← 200 : sfo1::2z8ld-1786828887035-a372fc5c4f79 [212ms]
> [debug] [2026-08-15T21:21:27.275Z] Error: Could not retrieve Project Settings. To link your Project, remove the `.vercel` directory and deploy again.
at getLinkedProject (file:///path/to/project/node_modules/vercel/dist/chunks/chunk-VE545BR3.js:61162:15)
at process.processTicksAndRejections (node:internal/process/task_queues:104:5)
at async ensureLink (file:///path/to/project/node_modules/vercel/dist/chunks/chunk-VE545BR3.js:59875:14)
at async pullCommandLogic (file:///path/to/project/node_modules/vercel/dist/chunks/chunk-LNVZ3T7X.js:157:16)
at async main (file:///path/to/project/node_modules/vercel/dist/chunks/chunk-LNVZ3T7X.js:143:22)
at async _Span.trace (/path/to/project/node_modules/@vercel/build-utils/dist/index.js:39171:14)
at async main (file:///path/to/project/node_modules/vercel/dist/index.js:2336:18)
Error: Could not retrieve Project Settings. To link your Project, remove the `.vercel` directory and deploy again.
Learn More: https://vercel.link/cannot-load-project-settings
> [debug] [2026-08-15T21:21:27.561Z] Vercel CLI 59.1.3 (Node.js 26.4.0)
> [debug] [2026-08-15T21:21:27.972Z] Telemetry event tracked
> [debug] [2026-08-15T21:21:27.991Z] Telemetry subprocess exited with code 0Success trace, when using a team-scoped token:
% VERCEL_ORG_ID=team_xxx VERCEL_PROJECT_ID=prj_xxx npx vercel pull --token=xxx --debug
> [debug] [2026-08-15T21:22:30.086Z] Found config in file "/path/to/project/vercel.json"
Vercel CLI 59.1.3 (Node.js 26.4.0)
> [debug] [2026-08-15T21:22:30.103Z] Agent/TTY/nonInteractive: isAgent=false agentName=none stdin.isTTY=true --non-interactive=false explicitFalse=false => nonInteractive=false
> [debug] [2026-08-15T21:22:30.103Z] user supplied known subcommand: "pull"
> [debug] [2026-08-15T21:22:30.254Z] Using token from `--token` argument, skipping token refresh.
> [debug] [2026-08-15T21:22:30.267Z] #1 → GET https://api.vercel.com/v2/user
> [debug] [2026-08-15T21:22:30.275Z] Spinner invoked (Retrieving project…) with a 1000ms delay
> [debug] [2026-08-15T21:22:30.277Z] #2 → GET https://api.vercel.com/teams/team_xxx
> [debug] [2026-08-15T21:22:30.278Z] #3 → GET https://api.vercel.com/v9/projects/prj_xxx?teamId=team_xxx
> [debug] [2026-08-15T21:22:30.365Z] #1 ← 200 : sfo1::swnbf-1786828950267-83bbfd23c514 [98ms]
> [debug] [2026-08-15T21:22:30.375Z] #2 ← 200 : sfo1::6hh45-1786828950273-9d9626049e94 [98ms]
> [debug] [2026-08-15T21:22:30.400Z] #3 ← 200 : sfo1::csqmx-1786828950288-22dcab12cc4e [122ms]
> Downloading `development` environment variables for radian-llcs-projects/domain-redirects
> [debug] [2026-08-15T21:22:30.402Z] Spinner invoked (Downloading) with a 300ms delay
> [debug] [2026-08-15T21:22:30.402Z] Fetching Environment Variables of prj_xxx and target development
> [debug] [2026-08-15T21:22:30.404Z] #4 → GET https://api.vercel.com/v3/env/pull/prj_xxx/development?source=vercel-cli%3Apull&teamId=team_xxx
> [debug] [2026-08-15T21:22:30.459Z] #4 ← 200 : sfo1::fllz5-1786828950355-e8b98ad77ca8 [55ms]
✓ Created .vercel/.env.development.local file
> Downloading project settings
✅ Downloaded project settings to /path/to/project/.vercel/project.json [0ms]
> [debug] [2026-08-15T21:22:30.729Z] Vercel CLI 59.1.3 (Node.js 26.4.0)
> [debug] [2026-08-15T21:22:31.139Z] Telemetry event tracked
> [debug] [2026-08-15T21:22:31.157Z] Telemetry subprocess exited with code 0Source: vercel/vercel