Fix Invalid API Key Errors on Vercel – Complete Env Var Guide

Vercel stores environment variables separately from the local .env files that are ignored by Git. Because the values are injected at build time, any change requires a new deployment. The process can be performed through the Vercel UI or the Vercel CLI, and each method allows you to target the three Vercel environments: Production, Preview, and Development.

Adding variables via the Vercel UI

1. Open the project in the Vercel dashboard.
2. Navigate to Project → Settings → Environment Variables.
3. Click Add Variable and enter the Key and Value.
4. Check the boxes for the environments that should receive the variable (Production, Preview, Development).
5. Save the entry.
6. Trigger a redeploy: go to Deployments → … → Redeploy or push a new commit.

Adding variables via the Vercel CLI

# Add a public variable for production
vercel env add NEXT_PUBLIC_SUPABASE_URL production

# Pull current values into a local .env file (development by default)
vercel env pull .env.local

# Add a secret for all environments
vercel env add OPENAI_API_KEY --secret --environment=preview

After using vercel env add, the CLI prints a confirmation and the variable becomes available only to subsequent builds. To apply the change immediately, run vercel deploy --prod or push a new commit.

Key considerations

• Variables without a public prefix (e.g., NEXT_PUBLIC_ for Next.js or VITE_ for Vite) are only available on the server side.
• Public‑prefixed variables are inlined into the client bundle; they must be redeployed to take effect.
• Secret keys (e.g., SUPABASE_SERVICE_ROLE_KEY, STRIPE_SECRET_KEY) should never use a public prefix and must remain server‑only.
• Typos, trailing spaces, or stray quotes in the value will cause runtime errors such as “Invalid API key”.
• Environment selection determines where the variable is injected: Production for live traffic, Preview for pull‑request builds, Development for local preview builds.

By following these steps, engineers can reliably propagate configuration changes across Vercel environments while ensuring that secret data remains protected and that client‑side variables are correctly prefixed and rebuilt.

Secret keys such as SUPABASE_SERVICE_ROLE_KEY, OPENAI_API_KEY, and STRIPE_SECRET_KEY grant full access to backend services. When these credentials are bundled into client‑side JavaScript they become visible to every visitor, allowing an attacker to invoke privileged APIs, bypass rate limits, or exfiltrate data. Compliance frameworks—including SOC 2, ISO 27001, NIST SP 800‑53, and the OWASP Application Security Verification Standard—require that authentication secrets be stored and used only in a trusted execution environment. Violating this principle creates a direct control‑plane exposure that most audits flag as a high‑severity finding.

In modern JavaScript frameworks the build process inlines any environment variable that carries a public prefix (NEXT_PUBLIC_ for Next.js, VITE_ for Vite). As the evidence notes, “Anything with NEXT_PUBLIC_ or VITE_ ends up in the JavaScript sent to every visitor.” Therefore, secret keys must be defined without those prefixes and accessed only in server‑only modules such as route handlers, server actions, or API routes.

Practical guidelines

• Define secrets without public prefixes. In Vercel or similar platforms add the variables directly (e.g., SUPABASE_SERVICE_ROLE_KEY) and mark them for the required environments.
• Restrict usage to server‑side code. Import process.env only inside files that run on the server (e.g., app/api/chat/route.ts).
• Fail fast on missing values. Use a helper that throws a clear error if a variable is undefined.
• Never expose keys in client bundles. Do not reference secret keys in components, pages, or any code that is compiled for the browser.
• Audit and rotate regularly. Follow the key‑rotation procedures required by your compliance framework.

Example of a safe server‑only handler in a Next.js 13 app:

 // app/api/chat/route.ts
export async function POST(req: Request) {
  const openAiKey = requireEnv('OPENAI_API_KEY'); // server‑only
  const body = await req.json();

  // Call OpenAI with the secret key – never sent to the client
  const response = await fetch('https://api.openai.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${openAiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });

  return new Response(await response.text(), { status: response.status });
}

function requireEnv(name: string) {
  const value = process.env[name];
  if (!value) throw new Error(`Missing env var: ${name}`);
  return value;
}

By keeping secret keys strictly on the server, you protect the integrity of your services, satisfy regulatory requirements, and reduce the attack surface exposed to end users.

Fail‑fast validation of environment variables prevents runtime surprises that are common when a build runs in a different execution context than the developer’s machine. In server‑side Node.js or edge runtimes, the process environment is available only at start‑up, so a missing key should abort early with a clear, actionable message.

/**
 * Throws if the requested variable is undefined, empty, or only whitespace.
 * Use this at the top of your entry point or in a dedicated config module.
 */
function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value || /^\s*$/.test(value)) {
    throw new Error(`Missing required environment variable: ${name}`);
  }
  return value;
}

// Example usage
const SUPABASE_URL = requireEnv('SUPABASE_URL');
const OPENAI_API_KEY = requireEnv('OPENAI_API_KEY');

When the function throws, the stack trace points directly to the missing variable, allowing developers to add the key in the CI/CD system (e.g., Vercel Settings → Environment Variables) and redeploy. This approach satisfies compliance frameworks such as NIST and ISO 27001, which require that secrets be validated before code execution.

Why dynamic lookups break in client‑side code

Frameworks that bundle JavaScript for the browser (Next.js, Vite, etc.) replace static references to process.env.VAR_NAME or import.meta.env.VAR_NAME at build time. The bundler cannot inline a value when the variable name is computed at runtime, so constructs like process.env[name] remain as literal property accesses in the shipped bundle. Because the browser never receives the full process.env object, the lookup resolves to undefined, producing errors such as “Invalid API key” or “supabaseUrl is required”.

• Static inlining required: Only variables with a known identifier are replaced.
• Public prefix needed: Variables intended for the client must be prefixed (e.g., NEXT_PUBLIC_ or VITE_) so the build tool knows to expose them.
• Redeploy after change: Adding or updating a prefixed variable requires a new build; the value is baked into the JavaScript bundle.
• Security boundary: Secrets without the public prefix stay server‑only, preventing accidental exposure.

Therefore, the recommended pattern is:

1. Declare required server‑side variables and validate them with requireEnv at start‑up.
2. Expose only safe, public variables using the framework‑specific prefix.
3. Reference those public variables directly (e.g., process.env.NEXT_PUBLIC_SUPABASE_URL) rather than via dynamic lookups.

When a deployment fails with “Invalid API key” or an undefined environment variable, the root cause is almost always a mismatch between the local development configuration and the runtime environment. The following checklist isolates the most common mis‑configurations and provides concrete steps to verify each one.

Troubleshooting checklist

• Confirm the variable exists in the Vercel dashboard and is marked for the correct environment (Production, Preview, or Development).
• Trigger a fresh build after any change; public prefixes (e.g., NEXT_PUBLIC_ or VITE_) are baked at build time, so a redeploy is required.
• Copy the key directly from the provider console; then remove surrounding quotes, trailing spaces, or newline characters.
• Verify you are using the appropriate key type: client‑side code must reference the public/anon key, never a service‑role or secret key.
• Run a guard clause at startup to fail fast if a required variable is missing:

  function requireEnv(name: string) {
    const v = process.env[name];
    if (!v) throw new Error(`Missing env var: ${name}`);
    return v;
  }

Common pitfalls

In Next.js, a variable without the NEXT_PUBLIC_ prefix is stripped from the client bundle, resulting in undefined at runtime. Vite uses the VITE_ prefix for the same purpose. Secret keys such as OPENAI_API_KEY or SUPABASE_SERVICE_ROLE_KEY must stay server‑only—store them without a public prefix and reference them inside API routes, Route Handlers, or Server Actions.

FAQ

Is the Supabase anon (public) key safe to expose?

Yes, it is intended for client use, but security relies on Row‑Level Security (RLS) policies being enabled on every table. Without RLS, the key can read or write unrestricted data.

Why does redeploying sometimes fix the issue?

Public‑prefixed variables are inlined during the build step. Changing their value in the dashboard does not affect an already built bundle; a new build incorporates the updated value.

What if the key works locally but fails in production?

Check that the variable is defined for the production environment in Vercel, that the correct prefix is used, and that the value contains no stray whitespace or quotation marks.