Introducción

EMFILE: too many open files parece un error simple. Rara vez lo es.

En una app serverless, ese mensaje no siempre significa que tu código está literalmente iterando sobre archivos en disco y olvidándose de cerrarlos. También puede significar que tu función abrió demasiados sockets, realizó demasiadas solicitudes salientes concurrentes, o alcanzó un límite de recursos durante un cold start al cargar un bundle de servidor grande.

Este artículo recorre un patrón de depuración que es útil mucho más allá de una sola base de código. Los ejemplos provienen de una app SvelteKit desplegada en Vercel, pero las lecciones aplican a muchas aplicaciones serverless basadas en Node.

La app tenía tres problemas superpuestos:

las dependencias pesadas exclusivas del servidor se estaban cargando demasiado temprano en los caminos de cold start
una ruta de análisis de administración estaba emitiendo demasiadas solicitudes respaldadas por Redis en paralelo
la carga de markdown sin procesar funcionaba en desarrollo pero dependía de suposiciones que eran frágiles en producción

La parte complicada era que estos problemas no fallaban de forma independiente. Se manifestaban a través de rutas cercanas, stack traces similares y un mensaje de error engañoso.

Qué Significa `EMFILE` Realmente en Entornos Serverless

A nivel del sistema operativo, EMFILE significa que el proceso ha agotado sus descriptores de archivo disponibles.

Por eso el texto del error dice "too many open files." Pero los descriptores de archivo no son solo archivos regulares en disco. También incluyen cosas como:

sockets
pipes
algunos handles de red
otros recursos del sistema operativo expuestos a través de descriptores

Ese detalle importa en Vercel. Si una función serverless realiza demasiadas solicitudes externas concurrentes, el fallo puede manifestarse como EMFILE incluso cuando la causa inmediata es presión de red en lugar de un mal bucle sobre el sistema de archivos local.

Entonces la primera regla útil de depuración es:

Cuando veas EMFILE en producción, investiga tanto el acceso al sistema de archivos como la concurrencia saliente.

Los Síntomas en Producción

Los fallos aparecieron en rutas relacionadas con administración y traducción.

Al principio, el error parecía un problema de cold start del bundle compartido. Era una hipótesis razonable porque las rutas en cuestión dependían de:

código de traducción
resaltado de sintaxis
caché respaldada por Redis
helpers exclusivos del servidor

Más tarde, una vez que los logs se inspeccionaron más de cerca, un segundo patrón se hizo visible: la ruta de análisis de administración estaba haciendo demasiado trabajo en paralelo contra Upstash Redis.

Al mismo tiempo, las herramientas de traducción tenían un bug separado exclusivo de producción: no podían encontrar de forma confiable los archivos fuente de markdown después del build, aunque los archivos existían y todo funcionaba localmente en desarrollo.

Esa mezcla es exactamente lo que hace que incidentes como este sean frustrantes. El stack trace a menudo apunta a donde la función finalmente falla, no necesariamente donde comenzó la presión arquitectónica.

Por Qué el Primer Diagnóstico Solo Fue Parcialmente Correcto

Una de las primeras cosas que inspeccionar en un fallo serverless es la forma del bundle del servidor.

Si una ruta importa estáticamente librerías costosas, esas dependencias pueden terminar en chunks compartidos del servidor que Vercel necesita inicializar durante el cold start. Esto aumenta el trabajo de inicio y puede producir fallos que parecen inestabilidad genérica del servidor.

En esta app, el camino de traducción usaba librerías que nunca deberían ser parte de un camino barato de cold start compartido. La ruta actual lo señala directamente:

// renderMarkdownHtml and translateBatch are dynamic — Shiki (hundreds of grammar
// files) and the Anthropic SDK must never enter the shared cold-start bundle.
// Dynamic import defers both until the first actual translation render.

Y las importaciones reales fueron movidas detrás de límites asincrónicos:

const { translateBatch } = await import('$lib/i18n/translate')
const { proseTranslations, title, description, diagnostics } = await translateBatch(
	prose,
	englishArticle.title,
	englishArticle.description,
	lang
)

const translatedMarkdown = reassemble(segments, proseTranslations)
const { renderMarkdownHtml } = await import('$lib/i18n/render')
const html = await renderMarkdownHtml(translatedMarkdown)

Esta fue una mejora real. Redujo la presión del cold start y mantuvo las dependencias pesadas de traducción fuera del camino predeterminado.

Pero no era toda la historia.

La lección importante es:

Una mejora en el cold start puede ser correcta y aun así no ser la corrección principal.

El Verdadero Cuello de Botella en Tiempo de Ejecución: Redis Fan-Out

La causa raíz más importante era la ruta de análisis de administración.

Esa ruta necesitaba muchas métricas:

visitantes únicos para múltiples rangos
páginas vistas para múltiples rangos
estadísticas por locale
rutas principales
países principales
búsquedas específicas por ruta

Ninguna de esas consultas era conceptualmente incorrecta. El problema era la cantidad de trabajo paralelo que sucedía a la vez.

La ruta ahora documenta la corrección claramente:

// 20 main queries — run in 5 batches of 4 to avoid too many concurrent
// Upstash HTTP connections on serverless cold starts.
const [siteUVToday, siteUV7d, siteUVMonth, siteUVYear] = await Promise.all([
	countSiteDays(today),
	countSiteDays(days7),
	countSiteMonth(ymYear, ymMonth),
	countSiteYear(year)
])

Este es el cambio crítico en la comprensión:

el bug no era "Redis es malo"
el bug no era "Upstash es incompatible"
el bug era concurrencia sin límite o excesiva para un camino de solicitud serverless

Cuando se crean muchas solicitudes HTTP de Redis salientes juntas, consumen recursos a través de sockets y descriptores relacionados. En una máquina local quizás nunca lo notes. En un entorno serverless con límites más estrictos, el mismo patrón puede colapsar en EMFILE.

En otras palabras:

El error parecía agotamiento del sistema de archivos, pero el problema dominante en tiempo de ejecución era el fan-out de solicitudes.

Por Qué los Dashboards de Admin Son un Lugar Común para que Esto Suceda

Las rutas de administración suelen ser engañosamente peligrosas.

Tienden a acumular:

resúmenes de análisis
reportes de "top N"
contadores transversales
filtros ad hoc
herramientas de inspección de caché
operaciones en lote

Cada característica parece pequeña de forma aislada. El problema es la cantidad total de trabajo en el backend desencadenado por una sola solicitud.

En este caso, la página de análisis de administración era efectivamente un amplificador de concurrencia. Agrupaba mucho trabajo respaldado por Redis en una sola ruta. Una vez que el tráfico de producción, los cold starts serverless y los límites de tiempo de ejecución estaban involucrados, la ruta se volvió frágil.

Por eso las herramientas internas merecen la misma disciplina de rendimiento que las rutas públicas.

El Estabilizador Secundario: Cachear la Respuesta de Análisis

Los límites de concurrencia ayudaron, pero no fueron la única corrección.

La ruta también agregó una caché de corta duración a nivel de módulo:

// Single admin user only. Cache key = ym:year only — path is intentionally
// excluded so a path lookup never busts the 20-query main analytics cache.
// TTL = 30s. Cleared explicitly on logout so a new session always sees fresh data.
let _cache: { key: string; ts: number; data: Record<string, unknown> } | null = null
const CACHE_TTL = 30_000

Esto no hace que el análisis sea "en tiempo real para siempre." Hace algo más útil:

la navegación repetida del admin ya no vuelve a disparar el conjunto completo de consultas costosas de inmediato
las búsquedas específicas por ruta pueden calcularse por separado
la ruta evita presión innecesaria durante el uso normal del operador

Este es un buen patrón para dashboards internos. Un TTL corto a menudo te da la mayor parte del beneficio con casi ninguna de la complejidad.

Por Qué el Flujo de Traducción Parecía Culpable

Las rutas de traducción eran parte de la misma superficie de depuración, por lo que atrajeron sospechas temprano.

Eso no era irracional. El camino de traducción sí incluía trabajo costoso:

cargar markdown sin procesar
dividir contenido en segmentos traducibles
llamar al modelo de traducción
renderizar HTML con resaltado
leer y escribir entradas de caché

Esos caminos eran genuinamente más pesados que una solicitud de página normal.

Pero la distinción clave es esta:

la complejidad de traducción contribuía al peso del bundle y la complejidad operacional
el fallo principal de EMFILE en Redis seguía siendo el fan-out de análisis de administración

Esa distinción importa porque de lo contrario puedes pasar mucho tiempo ajustando código de traducción mientras el riesgo de producción más grande permanece en otro lugar.

Un Bug Separado de Producción: Búsqueda de Markdown Sin Procesar

También había un fallo diferente en las herramientas de traducción: la app no siempre podía encontrar los archivos fuente de artículos en producción.

La parte confusa era que el contenido claramente existía y la misma búsqueda funcionaba en desarrollo.

Ese tipo de fallo es usualmente señal de una cosa:

el código depende de un layout del sistema de archivos del árbol de fuentes que no está garantizado después del build

La corrección más limpia fue dejar de usar suposiciones del sistema de archivos en tiempo de ejecución y en cambio dejar que Vite resuelva el markdown a través del grafo de módulos:

const rawPostModules = import.meta.glob('/src/posts/**/*.md', {
	import: 'default',
	query: '?raw'
})

export async function readPost(slug: string): Promise<string> {
	const postPath = `/src/posts/${slug}.md`
	const loader = rawPostModules[postPath]
	if (!loader) throw new Error(`Markdown not found: ${postPath}`)
	return (await loader()) as string
}

Esta es el tipo de corrección que no solo es más segura, sino más idiomática para SvelteKit:

sin adivinar el layout de la salida del build
sin dependencia en process.cwd() o rutas relativas en disco
sin discrepancia dev-versus-prod en cómo se resuelve el contenido

Ese problema era separado del problema de fan-out de Redis, pero era parte de la misma limpieza operacional.

Por Qué `import.meta.glob` Es una Mejor Opción que `fs` en Tiempo de Ejecución

En una app Vite/SvelteKit, import.meta.glob es a menudo la mejor elección cuando el contenido es parte de la aplicación misma.

¿Por qué?

usa la comprensión del bundler sobre el proyecto
sobrevive cambios en el layout de la salida del build
funciona consistentemente en desarrollo y producción
evita suposiciones del sistema de archivos específicas del despliegue

Este es un buen ejemplo de una regla más amplia:

Cuando el contenido de la aplicación es parte de tu árbol de fuentes, prefiere la resolución nativa del framework sobre la lógica de rutas en tiempo de ejecución construida a mano, siempre que sea posible.

Las Operaciones en Lote También Necesitan Disciplina de Concurrencia

Una vez que el problema de Redis quedó claro, también tenía sentido aplicar el mismo razonamiento a las operaciones en lote de administración.

El camino de traducción en lote ahora documenta ese límite explícitamente:

// Keep translation concurrency bounded so bulk admin runs do not create
// the same kind of serverless resource spike that previously contributed
// to EMFILE-style failures under high parallelism.
const BATCH = 5

Y el trabajo real se procesa lote por lote:

for (let i = 0; i < articles.length; i += BATCH) {
	const batch = articles.slice(i, i + BATCH)
	const settled = await Promise.allSettled(
		batch.map(async (article) => {
			const t0 = Date.now()
			const r  = await buildTranslateResult(article.slug, lang)
			if ('error' in r) throw new Error(r.error)

Esto no significa que la herramienta de traducción en lote haya causado el fallo original de análisis. Significa que el proceso de depuración expuso una regla general que vale la pena aplicar en toda la app:

evitar el paralelismo sin límite
especialmente en rutas exclusivas de administración
especialmente cuando hay servicios externos involucrados

Por Qué el Desarrollo Local No Expuso los Mismos Fallos

Gran parte de la frustración en la depuración de producción viene de una frase:

Pero funciona en localhost.

Esa frase era verdad aquí y aun así no era suficientemente útil.

El desarrollo y la producción diferían en varias formas importantes:

la forma del bundle del servidor era diferente
el layout de la salida del build era diferente
los cold starts serverless no existían localmente de la misma manera
los límites de recursos eran diferentes
los patrones de uso local no producían la misma presión de concurrencia

Entonces el hecho de que la app se comportara correctamente en desarrollo no eliminaba:

la presión del cold start
el fan-out de Redis
las suposiciones de caminos de contenido exclusivas de producción

Por eso "funciona localmente" debería tratarse como un punto de datos, no como un veredicto.

Un Método Práctico de Depuración para `EMFILE`

Cuando EMFILE aparece en una app serverless, el camino más rápido hacia la claridad es separar la investigación en tres categorías.

1. Preguntas sobre cold start y forma del bundle

Pregunta:

¿qué dependencias se importan estáticamente?
¿cuáles solo se necesitan en caminos de código reducidos?
¿qué podría estar entrando innecesariamente en chunks compartidos del servidor?

2. Preguntas sobre concurrencia en tiempo de ejecución

Pregunta:

¿cuántas solicitudes salientes hace esta ruta?
¿se lanzan todas a la vez?
¿puede el trabajo procesarse en lotes?
¿puede la ruta cachear resultados intermedios o finales?

3. Preguntas sobre suposiciones del entorno de producción

Pregunta:

¿este código asume un layout del sistema de archivos del árbol de fuentes local?
¿depende de rutas relativas que solo tienen sentido antes del build?
¿puede el framework resolver esto de forma más segura a través de su propio sistema de módulos?

Este enfoque es mucho más efectivo que tratar EMFILE como un bug puramente del sistema de archivos.

La Arquitectura Antes y Después

Antes:

las dependencias pesadas exclusivas del servidor eran más fáciles de jalar hacia caminos de bundle compartido
las consultas de análisis creaban demasiado trabajo paralelo en Redis
la carga de contenido dependía de suposiciones de rutas en tiempo de ejecución
las operaciones en lote de administración tenían menos salvaguardas explícitas

Después:

las dependencias pesadas de traducción se importan dinámicamente
las solicitudes de análisis se procesan en lotes de forma más conservadora
el caché de corta duración reduce la presión de consultas repetidas de administración
el markdown sin procesar se carga a través de import.meta.glob
las ejecuciones de traducción en lote de administración usan límites explícitos de concurrencia

El resultado no es solo un incidente resuelto. El resultado es una arquitectura del lado del servidor más resiliente.

Lecciones Reutilizables

La lección más útil de este ciclo de depuración es que los errores de producción a menudo tienen forma arquitectónica, no solo de líneas de código aisladas.

EMFILE resultó ser un síntoma de varias presiones de diseño que interactuaban:

una ruta que hacía demasiado trabajo en el backend a la vez
dependencias costosas en caminos de ejecución sensibles
patrones de acceso al contenido demasiado acoplados a las suposiciones del desarrollo local

Las correcciones siguieron un patrón reutilizable:

mover dependencias costosas detrás de importaciones dinámicas
limitar la concurrencia para llamadas a servicios externos
cachear trabajo costoso de administración cuando la frescura exacta en tiempo real no es necesaria
preferir la resolución de contenido nativa del framework sobre la adivinanza de rutas en tiempo de ejecución

Si solo recuerdas una línea de este artículo, que sea esta:

En plataformas serverless, EMFILE es a menudo un problema de forma de recursos antes de ser un problema de ruta de archivos.

Una Lista de Verificación para Tu Propia App

Si encuentras EMFILE en Vercel u otra plataforma serverless, revisa estos puntos en orden:

¿Estás lanzando demasiadas solicitudes externas en paralelo?
¿Alguna ruta de administración genera llamadas en cadena a Redis, base de datos o APIs?
¿Se están importando librerías pesadas de forma estática en código del servidor que debería mantenerse ligero?
¿La ruta está re-ejecutando trabajo costoso que podría cachearse brevemente?
¿Estás leyendo contenido del sistema de archivos de una manera que asume una estructura de directorio local?
¿Puede el framework resolver ese contenido de forma más segura con una API que conozca el proceso de build?

Esa lista de verificación generalmente te acercará más rápido a la causa real que solo mirar el texto crudo del error.

Conclusión

Las fallas en producción en este caso fueron difíciles no porque alguna corrección individual fuera complicada, sino porque los síntomas se superponían.

La ruta que parecía sospechosa no era el único problema. El texto del error era técnicamente correcto pero operacionalmente engañoso. El comportamiento en desarrollo era real pero no representativo. La solución final requirió tratar la aplicación como un sistema:

comportamiento en cold-start
concurrencia en tiempo de ejecución
ergonomía de administración
estrategia de carga de contenido

Eso es lo que convirtió este incidente en una referencia útil. No fue solo una lección sobre cómo corregir un error de Vercel. Fue un recordatorio de que el debugging en entornos serverless frecuentemente se trata de rastrear cómo la arquitectura se comporta bajo los límites de producción, y no solo de rastrear un único stack frame.

Introducción

Qué Significa EMFILE Realmente en Entornos Serverless

Los Síntomas en Producción

Por Qué el Primer Diagnóstico Solo Fue Parcialmente Correcto

El Verdadero Cuello de Botella en Tiempo de Ejecución: Redis Fan-Out

Por Qué los Dashboards de Admin Son un Lugar Común para que Esto Suceda

El Estabilizador Secundario: Cachear la Respuesta de Análisis

Por Qué el Flujo de Traducción Parecía Culpable

Un Bug Separado de Producción: Búsqueda de Markdown Sin Procesar

Por Qué import.meta.glob Es una Mejor Opción que fs en Tiempo de Ejecución

Las Operaciones en Lote También Necesitan Disciplina de Concurrencia

Por Qué el Desarrollo Local No Expuso los Mismos Fallos

Un Método Práctico de Depuración para EMFILE

1. Preguntas sobre cold start y forma del bundle

2. Preguntas sobre concurrencia en tiempo de ejecución

3. Preguntas sobre suposiciones del entorno de producción

La Arquitectura Antes y Después

Lecciones Reutilizables

Una Lista de Verificación para Tu Propia App

Conclusión

Qué Significa `EMFILE` Realmente en Entornos Serverless

Por Qué `import.meta.glob` Es una Mejor Opción que `fs` en Tiempo de Ejecución

Un Método Práctico de Depuración para `EMFILE`