vercel/ai · critical · HarnessSandboxAuthenticationError

Vercel Sandbox authentication failed. Set…

Error message

Vercel Sandbox authentication failed. Set VERCEL_OIDC_TOKEN, or pass token, teamId, and projectId to createVercelSandbox(), then verify that they can access Vercel Sandbox.

What it means

withVercelSandboxAuthenticationError wraps any underlying sandbox/auth error in a HarnessSandboxAuthenticationError when Vercel Sandbox cannot be authenticated. The library requires either an OIDC token from the environment or an explicit token/teamId/projectId configuration to create and access sandboxes. It rethrows the original error only in cases (reported via hasConfiguredCredentials) where misdiagnosing it as an auth failure would be wrong.

Solutions

Set VERCEL_OIDC_TOKEN in the environment (e.g. vercel env pull or run inside a Vercel deployment).
Pass explicit credentials to createVercelSandbox(): token, teamId, and projectId.
Verify the token/team/project can access Vercel Sandbox (feature enabled for the team).
Inspect the wrapped `cause` error for the true underlying failure.

Example fix

// before
const sandbox = await createVercelSandbox({ template: 'vercel/node:22' });
// after
const sandbox = await createVercelSandbox({
  template: 'vercel/node:22',
  token: process.env.VERCEL_TOKEN,
  teamId: 'team_xxx',
  projectId: 'prj_xxx',
});

Defensive patterns

Strategy: validation

Validate before calling

function canAuthenticateVercelSandbox(cfg) {
  return Boolean(
    process.env.VERCEL_OIDC_TOKEN ||
      (cfg?.token && cfg?.teamId && cfg?.projectId),
  );
}

Type guard

function isSandboxAuthError(e) {
  return HarnessSandboxAuthenticationError.isInstance(e);
}

Try / catch

try {
  await createVercelSandbox(opts);
} catch (error) {
  if (HarnessSandboxAuthenticationError.isInstance(error)) {
    throw new Error('Configure VERCEL_OIDC_TOKEN or token/teamId/projectId', { cause: error });
  }
  throw error;
}

Prevention

Ensure VERCEL_OIDC_TOKEN is present in the runtime environment before starting.
Store token/teamId/projectId in config and validate at startup.
Verify team/project has Vercel Sandbox enabled.
Always log the wrapped `cause` for diagnosis.

When it happens

Trigger: Calling createVercelSandbox(), or the sandbox/template/stopResult/createSession/fork APIs, without VERCEL_OIDC_TOKEN set and without passing token, teamId, and projectId; or passing credentials that lack access to Vercel Sandbox.

Common situations: Local scripts run outside Vercel deployments where VERCEL_OIDC_TOKEN is never injected; CI jobs missing the OIDC token env var; wrong teamId/projectId; a team or project that has not enabled Vercel Sandbox; expired OIDC tokens.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/543f67eec6eb7dde. Report an issue: GitHub.

Appendix: source

Thrown at packages/sandbox-vercel/src/vercel-sandbox.ts:344

async function withVercelSandboxAuthenticationError<T>({
  settings,
  operation,
}: {
  settings: VercelSandboxSettings;
  operation: () => Promise<T>;
}): Promise<T> {
  try {
    return await operation();
  } catch (error) {
    if (
      !isVercelSandboxAuthenticationFailure({
        error,
        hasConfiguredCredentials: hasConfiguredCredentials(settings),
      })
    ) {
      throw error;
    }
    throw new HarnessSandboxAuthenticationError({
      message: VERCEL_SANDBOX_AUTHENTICATION_MESSAGE,
      sandboxProviderId: VERCEL_PROVIDER_ID,
      cause: error,
    });
  }
}

function hasConfiguredCredentials(settings: VercelSandboxSettings): boolean {
  if (process.env.VERCEL_OIDC_TOKEN) return true;
  if ('sandbox' in settings && settings.sandbox != null) return true;
  const { token, teamId, projectId } = getSandboxLookupParams(settings);
  return Boolean(token && teamId && projectId);
}

function isVercelSandboxAuthenticationFailure({
  error,
  hasConfiguredCredentials,
}: {

View on GitHub (pinned to 69428b1f8b)