El error anthropic_api_key environment variable not set aparece en Vercel cuando el código corre en el servidor pero la variable de entorno no está configurada en el dashboard del proyecto. El problema no está en tu código: está en que las variables de entorno de Vercel no se propagan automáticamente desde tu máquina local, y hay que agregarlas manualmente en cada ambiente.
En 30 segundos
- El error ocurre en runtime de Vercel, no en build — tu
.env.localnunca llega al servidor en producción. - Tenés dos caminos: agregar
ANTHROPIC_API_KEYdirecto en Project Settings, o usar Vercel AI Gateway con tres variables distintas. - Si elegís AI Gateway,
ANTHROPIC_API_KEYdebe estar vacía o ausente — de lo contrario el SDK la va a usar en vez del Gateway y vas a seguir viendo el error. - Después de agregar cualquier variable en Vercel, tenés que hacer un redeploy manual para que el cambio tome efecto.
- Nunca uses
NEXT_PUBLIC_ANTHROPIC_API_KEY— eso expone tu clave al browser.
Claude API es una interfaz de programación (API) desarrollada por Anthropic que permite a desarrolladores integrar el modelo de lenguaje Claude en sus aplicaciones. Proporciona acceso programático a las capacidades de generación de texto, análisis y respuesta de preguntas de Claude.
¿Por qué falla anthropic_api_key en Vercel?
Las variables de entorno en Vercel viven en el dashboard del proyecto. No en tu repo, no en tu máquina, no en el .env.local que tenés en la raíz del proyecto. Cuando subís un deploy, Vercel inyecta las variables que configuraste en Project Settings al runtime del servidor — y solamente esas.
Lo que pasa cuando trabajás localmente: @anthropic-ai/sdk lee process.env.ANTHROPIC_API_KEY desde tu .env.local, funciona perfecto, publicás el código orgulloso y en producción explota con anthropic_api_key environment variable not set. (El error con minúsculas en el mensaje es confuso, pero se refiere a ANTHROPIC_API_KEY en mayúsculas — es el SDK que normaliza el nombre internamente.)
El SDK de Anthropic lanza este error específicamente cuando no encuentra la variable en el momento en que se instancia el cliente, que es en runtime del servidor. No en build time. Por eso el build puede pasar sin errores y el deploy falla igual.
Hay otro caso que se da seguido: configuraste la variable en Vercel, pero solo para el ambiente “Production” y estás probando en Preview. O agregaste la variable pero no hiciste redeploy después. Vercel no “recarga en caliente” las variables — cada cambio de variables requiere un nuevo deploy. Te puede servir nuestra cobertura de antes de empezar con Claude en Vercel.
Dos rutas: API directo vs Vercel AI Gateway
Antes de ponerte a configurar variables, conviene que elijas el enfoque. Hay dos caminos con lógicas distintas.
| Característica | API Anthropic directo | Vercel AI Gateway |
|---|---|---|
| Variables necesarias | Solo ANTHROPIC_API_KEY | ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN + ANTHROPIC_API_KEY (vacía) |
| Observabilidad | Solo lo que registres vos | Dashboard de Vercel con logs y métricas |
| Rate limiting | El de Anthropic (por plan) | Gateway agrega una capa propia |
| Cacheo de respuestas | No incluido | Sí, configurable |
| Costo adicional | Sin costo extra de plataforma | Incluido en planes de Vercel (con límites) |
| Complejidad de setup | Una variable, listo | Tres variables, más pasos |
Si estás arrancando o es un proyecto chico, el API directo alcanza. Si necesitás monitoreo de uso, querer limitar llamadas o el proyecto va a escalar, AI Gateway tiene sentido. Lo interesante es que podés cambiar de uno a otro sin tocar el código del SDK — solo cambiando las variables.
Paso a paso: Configurar variables de entorno Claude API en Vercel de forma directa
Este es el camino más corto. Cinco pasos:
- Paso 1: Obtené tu API key en console.anthropic.com. Si no tenés cuenta, el registro es gratuito con crédito inicial para testear.
- Paso 2: En el dashboard de Vercel, entrá a tu proyecto y andá a Settings > Environment Variables.
- Paso 3: Agregá una nueva variable con nombre
ANTHROPIC_API_KEYy tu clave como valor. Vercel la va a marcar automáticamente como “Sensitive” y la va a encriptar. - Paso 4: Seleccioná en qué ambientes querés que esté disponible: Production, Preview, Development. Si querés que funcione tanto en el deploy definitivo como en los previews de PRs, marcá los dos primeros.
- Paso 5: Hacé un redeploy manual desde Deployments. Las variables no se aplican a deploys anteriores.
Desde el código, accedés con process.env.ANTHROPIC_API_KEY en cualquier server component, API route o server action de Next.js. El SDK de Anthropic la levanta automáticamente si se llama ANTHROPIC_API_KEY.
Un detalle: según la documentación de Vercel sobre variables sensibles, las variables marcadas como “Sensitive” no se pueden leer en texto plano desde el dashboard una vez guardadas — solo se pueden reemplazar. Eso es buena señal de seguridad, no un bug.
Paso a paso: Configurar con Vercel AI Gateway
Este setup tiene más pasos y una trampa específica que genera muchos errores.
- Paso 1: En el dashboard de Vercel, andá a la sección “AI Gateway” y creá una API key del Gateway (distinta a tu key de Anthropic).
- Paso 2: Agregá la variable
ANTHROPIC_BASE_URLcon el valor de endpoint que te da Vercel para su Gateway. Ese valor lo encontrás en la documentación del AI Gateway de Vercel para la API de Anthropic. - Paso 3: Agregá
ANTHROPIC_AUTH_TOKENcon la API key del Gateway que creaste en el paso 1. - Paso 4: Agregá
ANTHROPIC_API_KEYcon valor vacío (una string vacía:"") o directamente no la agregues. - Paso 5: Redeploy.
La trampa del paso 4 es la más frecuente: si ANTHROPIC_API_KEY tiene tu clave real de Anthropic, el SDK la va a usar directo y va a ignorar completamente ANTHROPIC_BASE_URL y ANTHROPIC_AUTH_TOKEN. El SDK tiene precedencia de variables en ese orden, y con la key real presente bypasea el Gateway. (Sí, en serio. Y el error que obtenés no es obvio.)
Con el Gateway activo, tu proyecto también pasa por la capa de monitoreo de Vercel, que te da métricas de uso, latencia y costos desde el mismo dashboard donde gestionás el deploy. Más contexto en según el modelo de Claude que uses.
Errores comunes y cómo resolverlos
Variable no agregada a todos los ambientes
Configuraste la variable solo para “Production” y el error aparece en Preview. Vas a Settings > Environment Variables, editás la variable y marcás también “Preview”. Redeploy.
Olvidaste hacer redeploy
Este es el más común. Agregaste la variable, el dashboard la muestra, pero el deploy que está corriendo es anterior. Vercel no recarga variables en deploys existentes. Tenés que triggerear un nuevo deploy desde la pestaña Deployments.
Usaste NEXT_PUBLIC_ por error
Si nombrás la variable NEXT_PUBLIC_ANTHROPIC_API_KEY, Next.js la va a incrustar en el bundle del cliente y va a quedar expuesta en el browser. Cualquiera con las devtools la puede ver. La variable sin el prefijo NEXT_PUBLIC_ solo está disponible en el servidor — que es donde tiene que estar.
Espacios en blanco en la clave
Al pegar la API key en el formulario de Vercel es fácil que quede un espacio al principio o al final. Vercel no lo recorta automáticamente. El SDK envía la clave tal cual está y Anthropic devuelve un error de autenticación (que a veces se manifiesta como “variable no encontrada” dependiendo de la versión del SDK). Copiá la clave sin espacios, o revisá con un editor de texto antes de pegar.
Intentar leer la variable en el cliente
El error también aparece si llamás al SDK de Anthropic desde un Client Component de Next.js o desde código que corre en el browser. process.env.ANTHROPIC_API_KEY sin el prefijo NEXT_PUBLIC_ es undefined del lado del cliente. Si necesitás llamar a Anthropic desde el front, hacelo a través de una API Route en el servidor. Relacionado: cómo integrar la API de Anthropic.
Seguridad: protegé tu API key
Ponele que subiste .env.local a git por accidente (o porque alguien en el equipo no sabía). La clave queda expuesta en el historial aunque después borres el archivo. Si eso pasa, rotá la key inmediatamente desde console.anthropic.com — no alcanza con borrar el archivo del repo.
Algunas prácticas que vale la pena tener desde el inicio:
- Agregá
.env.localy.enva tu.gitignoreantes del primer commit. - En console.anthropic.com podés crear claves con permisos limitados (por ejemplo, solo para ciertos modelos o con límite de gasto).
- Vercel encripta las variables sensibles por defecto — no aparecen en texto plano en los logs ni en el dashboard después de guardadas.
- Revisá periódicamente el uso de tu clave en el dashboard de Anthropic para detectar actividad inusual.
Si el proyecto usa hosting para el backend fuera de Vercel, vale mencionar que en donweb.com también podés configurar variables de entorno en los planes de hosting administrado para proyectos Node.js.
Cómo verificar que tu configuración funciona
Después del redeploy, tres formas de confirmar que la variable está disponible:
Desde los logs de Vercel: Deployments > [el deploy más reciente] > Functions. Ahí aparecen los logs de runtime. Si el error persiste, lo vas a ver ahí con el stack trace completo.
Con un endpoint de debug temporal: Creá una API route que devuelva process.env.ANTHROPIC_API_KEY ? "OK" : "FALTA". ¿Y qué pasa si la variable tiene valor pero es inválida? El SDK va a fallar con un error 401 de Anthropic, no con “not set” — eso te dice que la variable llega pero la clave no es válida.
Eso sí: borrá ese endpoint de debug antes de subir a producción. Aunque no expone la clave completa, confirma su presencia.
Localmente con las variables de Vercel: Si instalaste el CLI de Vercel (npm i -g vercel), podés correr vercel env pull .env.local para bajar las variables configuradas en el proyecto a tu entorno local. Útil para sincronizar sin tener que copiar manualmente.
Preguntas Frecuentes
¿Por qué funciona localmente pero falla en el deploy de Vercel?
Porque tu .env.local solo existe en tu máquina. Vercel no tiene acceso a ese archivo y no lo sube al servidor. Las variables de entorno en Vercel se configuran exclusivamente en el dashboard del proyecto (Settings > Environment Variables) y se inyectan en cada deploy nuevo desde ahí. Sobre eso hablamos en en deployments de aplicaciones grandes.
¿Debo usar ANTHROPIC_API_KEY o ANTHROPIC_AUTH_TOKEN?
ANTHROPIC_API_KEY es la variable estándar para el SDK de Anthropic apuntando directo a la API. ANTHROPIC_AUTH_TOKEN se usa junto con ANTHROPIC_BASE_URL cuando el tráfico pasa por Vercel AI Gateway — en ese caso es tu key del Gateway, no tu key de Anthropic. Si usás API directo, solo necesitás ANTHROPIC_API_KEY.
¿Qué es Vercel AI Gateway y cuándo conviene usarlo?
Vercel AI Gateway es una capa de proxy entre tu aplicación y los proveedores de IA (Anthropic, OpenAI, entre otros). Te da monitoreo de requests, cacheo de respuestas y rate limiting gestionado desde el dashboard de Vercel. Conviene cuando necesitás visibilidad de costos por proyecto, querés cachear respuestas para reducir latencia o tenés múltiples servicios llamando a Anthropic y necesitás centralizar el control.
¿Por qué hay que dejar ANTHROPIC_API_KEY vacía cuando uso AI Gateway?
El SDK de Anthropic tiene una lógica de precedencia: si encuentra ANTHROPIC_API_KEY con valor, la usa directo y no respeta el ANTHROPIC_BASE_URL que apunta al Gateway. Para que el tráfico pase por el Gateway necesitás que esa variable esté ausente o vacía, y poner tu key del Gateway en ANTHROPIC_AUTH_TOKEN.
¿Qué pasa si agrego la variable pero no hago redeploy?
El deploy en producción sigue corriendo con el snapshot de variables que tenía cuando fue desplegado. Las variables nuevas o modificadas no se aplican a deploys existentes. Tenés que triggerear un redeploy desde la pestaña Deployments para que el servidor levante las variables actualizadas.
Conclusión
El error anthropic_api_key environment variable not set en Vercel casi siempre tiene la misma causa: la variable está en tu máquina pero no en el dashboard del proyecto. El fix es ir a Settings > Environment Variables, agregar ANTHROPIC_API_KEY, seleccionar los ambientes correctos y hacer redeploy.
Si elegís Vercel AI Gateway, el setup tiene un paso contraintuitivo que atrapa a mucha gente: ANTHROPIC_API_KEY tiene que estar vacía para que el Gateway funcione. Una vez que entendés esa lógica de precedencia, el resto del setup es directo. Cualquiera que ya pasó por esto sabe que el tiempo que se pierde debuggeando esto es inversamente proporcional a lo simple que es la solución.