Error al desplegar con Replit Agent: causas y soluciones
Por qué tu app de Replit funciona en Preview pero falla al publicar, cómo leer los logs y cómo arreglar puertos, Secrets, comando de inicio y health check.
Read in English →
Si tu app hecha con Replit Agent funciona en Preview pero no se publica, casi siempre es por una de cinco cosas: el servidor escucha en localhost en vez de 0.0.0.0, la configuración de puertos no coincide, faltan los Secrets de producción, el comando de inicio termina en lugar de dejar un servidor corriendo, o la página principal tarda demasiado y no pasa el chequeo de salud de Replit. La pestaña Logs del panel de publicación te dice cuál de ellas es.
En esta guía revisamos cada causa en el orden en que conviene buscarla, cómo se ve el arreglo y qué hacer en el otro caso típico: la publicación sale bien, pero la URL en vivo no funciona.
¿La app funciona de verdad en Preview?
Empieza por aquí, porque publicar no arregla una app que ya está rota. Ejecuta la app desde el editor del proyecto y confirma que la vista previa (la dirección replit.dev) carga y que el flujo principal funciona: registrarte, iniciar sesión, crear algo y verlo guardado.
Si también falla en Preview, el problema no es el despliegue. Corrige primero el error en el espacio de trabajo y después vuelve a publicar.
¿Dónde veo el error real?
Abre el panel Publishing y entra a la pestaña Logs. Lee desde el inicio del intento fallido, no desde el final. Busca:
- Un stack trace con nombre de archivo y número de línea.
Cannot find moduleo un paquete que falta.- Un comando que falló durante el build.
- Una variable que vale
undefinedal arrancar.
Copia la primera línea de error real. Si le pides ayuda a Agent, pégale esa línea en lugar de escribir "falló el despliegue". Con un error concreto acierta mucho más.
¿Por qué falla si en Preview funciona?
1. El servidor escucha en la dirección equivocada
La documentación de Replit lo dice claramente: una app publicada tiene que escuchar en 0.0.0.0. Un servidor atado a localhost o 127.0.0.1 puede verse bien en el editor y fallar al publicarse.
En Express el cambio es una línea:
const port = process.env.PORT || 3000;
app.listen(port, "0.0.0.0");En Python con Flask o FastAPI, usa host="0.0.0.0" (o --host 0.0.0.0 en Uvicorn).
2. Los puertos no coinciden
Replit suele detectar tu puerto solo. El detalle: si tu archivo .replit tiene una sección [[ports]], la detección automática se apaga. En ese caso, la entrada de tu app debe mapear externalPort = 80 al localPort que tu servidor usa de verdad. Un error frecuente de Agent es dejar una entrada vieja después de cambiar de framework, y la plataforma termina revisando un puerto donde no escucha nadie.
Abre .replit, revisa cada bloque [[ports]] y elimina los que sobran o corrige el localPort para que coincida con el servidor.
3. Faltan los Secrets de producción
Este le pasa a casi todo el mundo. Los Secrets que configuras en el editor no pasan solos a la app publicada: se agregan aparte, en el panel Publishing.
Las señales típicas son errores de valores indefinidos al arrancar, llamadas fallidas a una API como OpenAI o Stripe, una base de datos que no conecta y un login o un pago que solo fallan en el sitio en vivo. Recorre todos los Secrets del espacio de trabajo y confirma que la app publicada tiene su propio valor. Usa claves reales solo donde de verdad las quieres.
4. El comando de inicio termina
Replit espera que una app publicada siga corriendo. Si tu comando ejecuta algo que termina (un script de datos de prueba, un build que nunca levanta el servidor, una migración suelta), Replit lo reinicia y la app nunca queda sana.
Revisa los comandos de build y de ejecución en el panel de publicación. En un proyecto Node lo normal es compilar primero (npm run build) y luego arrancar un proceso que se queda vivo (npm run start). Errores de tipeo, archivos de entrada equivocados y comandos que solo funcionaban en la computadora de alguien son muy comunes aquí.
5. La página principal es demasiado lenta para el chequeo
Antes de dar por publicada la app, Replit le envía una petición. Según su guía de solución de problemas, si la página principal tarda más de cinco segundos en responder, la publicación puede fallar en el último paso.
Las apps que arma Agent a veces hacen trabajo pesado en la primera petición: cargar muchos datos, llamar a un modelo de IA o correr migraciones al arrancar. Pasa ese trabajo a una acción del usuario, guárdalo en caché o ejecútalo después de que el servidor ya esté escuchando.
¿Elegiste el tipo de despliegue equivocado?
Un despliegue Static solo sirve archivos HTML, CSS y JavaScript. Si tu app tiene rutas de API, callbacks de login, consultas a la base de datos desde el servidor o cualquier lógica de backend, necesita Autoscale o Reserved VM. Se cambia en el panel de publicación. En nuestra guía sobre por qué una app de Replit se duerme explicamos las diferencias entre cada tipo.
El tamaño es el otro límite: la documentación de Replit habla de 8 GB para Autoscale y Reserved VM, y de 1 GB para Static. Archivos grandes subidos por error (videos, datasets, copias de node_modules) pueden hacerte pasar el límite.
La publicación salió bien, pero el sitio en vivo no funciona
Compara la app en vivo con Preview en estos puntos, que son los sospechosos de siempre:
| Revisa | Lo que suele fallar |
|---|---|
| Secrets y variables de entorno | Están en el editor, faltan en Publishing |
| Base de datos | La app sigue apuntando a la base de desarrollo |
| URL de redirección del login | El proveedor solo acepta la dirección replit.dev |
| Webhooks de pago | Stripe envía eventos a la URL vieja o con claves de prueba |
| CORS y listas de dominios permitidos | El dominio nuevo no está en la lista |
| Archivos guardados en disco | Se pierden en cada publicación |
La última fila merece una aclaración. Replit indica que el sistema de archivos de una app publicada no es persistente y se reinicia cada vez que publicas. Si las fotos de perfil desaparecen después de una actualización, es por eso. Guarda los archivos en una base de datos o en un servicio de almacenamiento. En la guía sobre la base de datos de Replit en producción vemos dónde debe vivir cada dato.
¿Cómo evito que vuelva a pasar?
- Lleva una lista corta de todos los Secrets que necesita la app y actualízala cada vez que Agent agregue una integración.
- Lee los cambios antes de aceptar ediciones grandes de Agent en
.replit,package.jsono el archivo de entrada del servidor. - Después de cada publicación, prueba la URL en vivo en una ventana privada: registro, login y la acción principal.
- Vigila los logs el día siguiente a un cambio grande. En la guía de monitoreo y errores en producción te mostramos cómo recibir alertas en vez de enterarte por tus usuarios.
Para una preparación más completa, revisa cómo pasar una app de la vista previa a producción.
Respuestas rápidas
¿Por qué mi app de Replit funciona en Preview pero no publicada? Lo más común es que falten los Secrets en el panel Publishing, que el servidor escuche en localhost en lugar de 0.0.0.0 o que el puerto de .replit no coincida con el del servidor.
¿Dónde están los logs del despliegue en Replit? En el panel Publishing, pestaña Logs. Lee el primer error del intento fallido.
¿Replit Agent puede arreglar solo un despliegue fallido? Muchas veces sí, si le das la línea exacta del error. Lo que no puede es cargar tus Secrets de producción ni adivinar qué claves reales quieres usar.
¿Por qué desaparecen los archivos subidos al publicar? Porque el sistema de archivos publicado se reinicia en cada publicación. Guárdalos en una base de datos o en un servicio de almacenamiento.
¿Sigues atascado?
Si los logs no apuntan a nada claro, pasa tu URL en vivo por la revisión gratuita de tu app para ver lo que se nota desde afuera. Si prefieres delegarlo, nuestro servicio para arreglar apps de Replit empieza revisando el código y la configuración de publicación, y cada arreglo tiene un precio cerrado que apruebas antes. También puedes contarnos el problema y una persona te responde en un día hábil.
