Orbit
Solución de problemas de compilaciones fallidas
When an Orbit build fails, the deployment detail page gives you the full log plus a categorised failure summary and a suggested fix. This guide walks through reading that page, the failures Orbit…
Cuando una compilación de Orbit falla, la página de detalles de implementación te proporciona el registro completo más un resumen de fallos categorizado y una solución sugerida. Esta guía te explica cómo leer esa página, los fallos que Orbit reconoce por nombre, los que no reconoce, y qué hacer cuando una compilación tiene éxito pero el sitio sigue siendo incorrecto.
Lectura del Fallo
- Abre tu proyecto en Orbit.
- Abre la pestaña Deployments.
- Haz clic en la implementación con estado Failed.
- Lee el resumen de fallos encima del registro primero, luego el registro mismo.
Orbit asigna a cada fallo una categoría: Out of memory, Compile error, Test failure, Lint error, Install error, Network error, Timeout, o Unknown error. La categoría te indica qué parte del pipeline debes revisar antes de leer una sola línea del registro.
También hay un botón Get AI diagnosis. Lee las últimas 120 líneas del registro junto con el framework detectado y la categoría de fallo, y devuelve una explicación en lenguaje natural.
El diagnóstico está etiquetado como AI-generated, verify before acting. Trátalo como un indicador muy útil de la línea correcta del registro, no como una autoridad sobre tu código. Lee la línea a la que se refiere antes de cambiar nada.
Si la compilación nunca comenzó y está atrapada en Queued, salta a la sección de compilaciones en cola más abajo.
Fallos que Orbit Reconoce Por Nombre
Estos vienen con una solución sugerida específica en la página de implementación.
| Lo que Orbit detecta | Qué significa | Solución |
|---|---|---|
| Missing module | Una importación apunta a un paquete que no está instalado | Añade el paquete a package.json y confirma, o corrige el error tipográfico en la ruta de importación |
ERESOLVE conflict | npm no puede satisfacer una dependencia de pares | Resuelve el conflicto en package.json, o añade --legacy-peer-deps a tu comando de instalación en Settings |
| TypeScript error | La verificación de tipos falló durante la compilación | Corrige los errores listados. Para problemas de tipos de terceros, skipLibCheck: true en tsconfig.json |
| Out of memory | La compilación superó la RAM de la máquina de compilación | Añade NODE_OPTIONS=--max-old-space-size=2048 como variable de entorno, o cambia a un plan con una máquina de compilación más grande |
| Build disk full | La compilación llenó su disco | Busca un node_modules o artefacto inesperadamente grande, o cambia a un plan con un disco de compilación más grande |
| Build timed out | La compilación alcanzó el límite de 30 minutos | Activa caché de compilación, reduce el tamaño del bundle, o encuentra qué está colgado |
| Package not found (404) | Una dependencia no existe con ese nombre o versión | Busca un error tipográfico en package.json, o confirma que el paquete está publicado |
| ESLint errors | Los errores de lint bloquearon la compilación | Corrígelos, o detén que lint cause fallo en la compilación en tu configuración de framework |
| Syntax error | Fuente no interpretable | Paréntesis faltante, cadena sin cerrar, o sintaxis que tu versión de Node no soporta |
| File not found | Un archivo referenciado no está en el repositorio | Confirma que está confirmado, y comprueba la mayúscula/minúscula de la ruta |
| Lockfile out of date | El lockfile no coincide con package.json | Ejecuta la instalación de tu gestor de paquetes localmente y confirma el lockfile actualizado |
El desajuste de lockfile es el fallo de primera implementación más común y el más confuso, porque nunca ocurre localmente. npm ci, yarn install --frozen-lockfile y pnpm install --frozen-lockfile se niegan a proceder cuando el lockfile no coincide con package.json. Regenera el lockfile localmente y confirma.
Fallos Comunes Por Fase
La Instalación de Dependencias Falla
La fase Install lanzó un error.
- Gestor de paquetes incorrecto. Orbit elige npm, yarn o pnpm desde tu lockfile. Si más de un lockfile está confirmado, la selección puede no ser la que esperas. Elimina los que no usas, o establece Install command explícitamente en Settings.
- Registro privado. Si una dependencia proviene de un registro privado, el token de autenticación tiene que estar disponible en tiempo de compilación como variable de entorno, y tu
.npmrctiene que referenciarlo. - Desajuste de versión de Node.js. Algunos paquetes requieren una versión mínima de Node. Establece Node.js version en Settings al número de versión principal:
18,20o22. - Falta de memoria en un monorepo grande. Usa
npm cien lugar denpm install, y considera un plan con una máquina de compilación más grande.
El Comando de Compilación Falla
La fase Build lanzó un error.
- Errores de TypeScript o lint. Orbit ejecuta tu comando de compilación exactamente como está escrito. Si tu compilación falla localmente, falla aquí.
- Variable de entorno de tiempo de compilación faltante. Una variable leída durante la compilación tiene que existir antes de que la compilación se ejecute, no solo en tiempo de ejecución. Añádela en la pestaña Env vars y reimplementa. Una variable de tiempo de compilación añadida después de una implementación no se aplica retroactivamente a ella.
- Directorio raíz incorrecto en un monorepo. Establece Root directory en Settings a la ruta de la aplicación, por ejemplo
apps/web.
Las Compilaciones Agotan el Tiempo
Las compilaciones se abortan a los 30 minutos de tiempo real en cada plan. Si la tuya consistentemente se aproxima a eso:
- Comprueba el log para un proceso esperando entrada. Una compilación que solicita información es una compilación que se cuelga.
- Evita
--legacy-peer-depsen un árbol de dependencias grande a menos que lo necesites. - Asegúrate de que se está utilizando la caché de compilación. Los planes Liftoff y Apex lo incluyen; la página de implementación muestra Cache hit o Cold build.
- Cambia a un plan con más vCPU de compilación. Ver Límites del Plan Kapsule Orbit.
La Compilación Nunca Comienza
Una implementación atascada en Queued está esperando un espacio de compilación. La página de detalles muestra tu posición en la cola y cuántos de tus espacios de compilación concurrentes están en uso, e inicia la compilación automáticamente cuando uno se libera. Launch y Liftoff permiten una compilación concurrente; Apex permite tres.
Puedes ver todo en vuelo en tu cuenta en Kapsule Orbit, luego Queue.
Si una implementación permanece en cola sin nada más en ejecución, es más probable que esté retenida en lugar de en cola. Comprueba:
- Awaiting approval, si Require approval for production está activo
- Un deploy lock en el proyecto
- Un deploy freeze schedule bloqueando la hora o día actual
- CI required checks esperando en tu pipeline
- Require staging success before production esperando una implementación de staging del mismo commit
La Compilación Fue Omitida Completamente
Si un push no produjo ninguna implementación, probablemente fue filtrado a propósito:
- Ignored paths: cada archivo en el push coincidió con un patrón como
*.mdodocs/** - Branch ignore patterns: la rama coincidió con algo como
dependabot/* - Root directory: nada en el push tocó el subdirectorio del monorepo para este proyecto
- Branch previews desactivado, y el push no fue a producción o staging
Compilación Exitosa Pero el Sitio es Incorrecto
Una compilación verde y un sitio roto es casi siempre un problema de configuración en lugar de un problema de código.
404 en cada página. El Output directory es incorrecto: Kapsule Orbit publicó una carpeta que no es tu resultado de compilación. Comprueba qué escribe realmente tu compilación. Los valores comunes son dist, .next, out, build y .output.
404 solo en rutas dinámicas. La aplicación necesita un servidor en ejecución y se está sirviendo como archivos estáticos. Activa Server mode en Settings bajo Runtime. Esto es necesario para Next.js con SSR, Remix, Nuxt y cualquier otra cosa que no sea una exportación estática.
Assets 404 después de un deploy, para usuarios que ya estaban en el sitio. Cargaron la página antigua y están solicitando URLs de bundle antiguas que ya no existen. Activa Skew protection en Settings, que mantiene los artefactos de compilación anterior disponibles durante una ventana de retención después de que una nueva implementación se ponga en vivo.
Variable de entorno no definida en tiempo de ejecución. Confirma que el alcance de la variable realmente cubre este entorno, y que la implementación es posterior al cambio. La página de detalles de implementación enumera exactamente qué claves se inyectaron en tiempo de compilación y las compara con tu configuración actual.
La configuración de compilación específica del framework está en Configurar tu Comando de Compilación y Directorio de Salida.
Reintentos
En la página de implementación fallida:
- Retry build vuelve a ejecutar el mismo commit.
- More retry options, luego Retry with cleared cache, elimina la caché de compilación primero.
También puedes hacer que Kapsule Orbit lo reintente por ti. Build auto-retry en Settings vuelve a encolar compilaciones fallidas causadas por errores de infraestructura como un error de red o un timeout, hasta tres veces. Deliberadamente no reintenta errores de código, por lo que una compilación, lint o fallo de prueba nunca se repite.
Reintentar con una caché borrada elimina el node_modules en caché para el entorno y no se puede deshacer. La siguiente compilación después de esto será lenta. Ese es el punto, pero no lo hagas reflexivamente en un monorepo grande.
Detener una Compilación Mala Llegando a los Usuarios
Si una implementación ya se ha puesto en vivo y rompió algo, revierte en lugar de intentar arreglarlo hacia adelante bajo presión. La reversión promueve un artefacto ya compilado y toma segundos. Ver Reversión de una Implementación.
Para detener futuras implementaciones mientras investigas, haz clic en Lock deploys en el proyecto. Las implementaciones activadas por push se omiten hasta que desbloquees, mientras que las implementaciones manuales aún funcionan para que puedas enviar la corrección.
También puedes hacer que Kapsule Orbit haga esto automáticamente: Auto-rollback on failure restaura la última implementación saludable cuando una implementación de producción falla, y un Health check la restaura cuando la nueva implementación no responde con un 2xx en 15 segundos.
Aún Atascado
Si el log simplemente termina sin mensaje de error, el proceso de compilación probablemente fue eliminado: sin memoria, o la máquina de compilación fue recuperada. Reintenta una vez. Si falla de la misma manera dos veces, abre un ticket desde KPanel o envía un correo a support@kapsulehost.com e incluye el ID de implementación que se muestra en la página de detalles.