Cómo solucionar una página en blanco en tu app web
Una página en blanco casi siempre significa una de dos cosas: el JavaScript de la app falló antes de dibujar nada, o el JavaScript nunca se cargó. Abre la consola del navegador (clic derecho → Inspeccionar → Consola) y lee el primer error en rojo; después revisa la pestaña Red (Network) para ver qué archivos no se cargaron. La mayoría de las causas son una variable de entorno que falta, una ruta base incorrecta, una compilación que no terminó o un fallo en un componente.
Esta guía cubre las apps de una sola página creadas con React, Vue o frameworks similares (incluidas las apps hechas con creadores con IA), que es donde más se dan las páginas en blanco.
Por qué la página está en blanco
Una aplicación moderna de una sola página (SPA) envía al navegador un archivo HTML casi vacío, más o menos así:
<body>
<div id="root"></div>
<script type="module" src="/assets/index-a1b2c3.js"></script>
</body>
Después, el JavaScript construye toda la página dentro de ese div vacío. Si el script no se carga, o lanza un error antes de renderizar, el div se queda vacío y ves blanco. La página no está «rota» de forma visible; simplemente nunca se dibujó.
Por eso la solución siempre empieza en las herramientas de desarrollo, no en la propia página.
Paso 1: lee la consola
Abre las herramientas de desarrollo: haz clic derecho en la página y elige Inspeccionar, o pulsa F12 (Cmd+Opción+I en un Mac). Ve a la pestaña Consola y recarga la página.
Fíjate en el primer error en rojo; los siguientes suelen ser efectos secundarios. Lo que dice indica la causa:
| Mensaje de la consola (redacción habitual) | Qué significa | Ve a |
|---|---|---|
Cannot read properties of undefined (reading '...') | El código esperaba datos que no estaban | Paso 4 |
... is not defined / ... is not a function | Falta un import, una variable o una configuración | Paso 4 o Paso 3 |
Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "text/html" | La URL de un script devolvió una página HTML en lugar de JavaScript | Paso 2 |
Uncaught SyntaxError: Unexpected token '<' | Lo mismo: HTML donde se esperaba JavaScript | Paso 2 |
supabaseUrl is required, Missing API key, o similar | Una variable de entorno está vacía | Paso 3 |
Access to fetch ... has been blocked by CORS policy | Se bloqueó una petición a otro dominio | Consulta cómo solucionar errores de CORS |
| Ningún error | El renderizado funcionó pero no muestra nada, o un CSS lo oculta | Paso 6 |
Copia el texto completo del error, incluidos el nombre del archivo y el número de línea. Si usas un creador con IA, pégalo directamente en el chat.
Paso 2: comprueba que los archivos se cargaron
Abre la pestaña Red (Network), marca Deshabilitar caché y recarga. Revisa las peticiones de archivos .js y .css.
- Estado 404 en un archivo JavaScript: la página pide un archivo que no está en el servidor.
- Estado 200 pero el tipo es
text/html: el servidor devolvió una página (a menudo el propioindex.html, por un fallback SPA) en lugar del script. La causa raíz es la misma: el archivo no está donde la página espera.
Motivos habituales:
Ruta base incorrecta. Si la app se sirve desde una subcarpeta, como ejemplo.com/app/, pero se compiló para cargar archivos desde /assets/..., cada petición de script fallará. En Vite esto es la opción base de vite.config; en Create React App es el campo homepage; en Next.js es basePath. Debe coincidir con el lugar donde la app se sirve realmente.
index.html desactualizado. Las herramientas de compilación ponen a los archivos nombres con un hash de contenido, como index-a1b2c3.js. Tras un nuevo despliegue, el archivo antiguo desaparece. Si un navegador o una CDN aún tiene en caché el index.html antiguo, pide el archivo viejo y no obtiene nada. Una recarga forzada (Cmd+Shift+R o Ctrl+Shift+R) lo confirma. La solución a largo plazo es servir index.html con una cabecera de caché corta o sin caché, mientras los archivos con hash se guardan en caché durante mucho tiempo.
La compilación no terminó o no se desplegó. Si la compilación falló, el hosting puede estar sirviendo una carpeta de salida antigua o vacía. Revisa el registro de compilación en busca de errores.
Se publica la carpeta equivocada. El hosting debe servir la salida de compilación (normalmente dist o build), no la carpeta de código fuente del proyecto. Servir el código fuente te da un index.html que apunta a /src/main.tsx, que los navegadores no pueden ejecutar.
Paso 3: comprueba las variables de entorno
Las apps de front end suelen leer ajustes como una URL de API o una clave pública durante la compilación. Si falta una variable en la compilación en vivo, código como createClient(undefined, undefined) lanza un error de inmediato y la página se queda en blanco.
Cosas que conviene saber:
- En Vite, solo las variables con el prefijo
VITE_están disponibles en el código del navegador, y se leen comoimport.meta.env.VITE_NAME. En Create React App esREACT_APP_; en Next.js,NEXT_PUBLIC_. - Estos valores se integran en el momento de compilar la app. Añadir una variable después de la compilación no hace nada hasta que vuelvas a compilar y desplegar.
- La vista previa o tu máquina local pueden tener un archivo
.envque la compilación de producción no tiene. Configura las mismas variables en el hosting. - Todo lo que lleva estos prefijos acaba en el JavaScript público. Pon ahí solo valores públicos, nunca claves secretas.
Una prueba rápida: busca en el error de la consola un undefined cerca del nombre de una configuración, o pregunta:
La app publicada muestra una página en blanco. Enumera todas las variables de entorno que lee el front end, comprueba cuáles faltan o están vacías en la compilación en vivo y haz que la app muestre un mensaje de error claro en lugar de una página en blanco cuando falte alguna.
Paso 4: corrige el fallo
Si la consola muestra un error normal de JavaScript, el código falló durante el renderizado. Causas típicas en apps creadas con IA:
- Datos que aún no se han cargado. Un componente lee
user.nameantes de queuserhaya llegado. La solución es un estado de carga, o el encadenamiento opcional (user?.name). - Datos vacíos. Una cuenta nueva no tiene registros, y el código supone que la lista tiene al menos un elemento.
- Forma de datos inesperada. Una API devolvió un objeto de error en lugar de la lista que esperaba el código.
- Un import que falta después de renombrar o mover un archivo.
- Usar una API exclusiva del navegador durante el renderizado en servidor, como
windowolocalStorageen un componente de servidor de Next.js.
Dale a la IA el error completo, la página y con qué cuenta estabas conectado:
La página Dashboard aparece en blanco para los usuarios nuevos. Consola:
TypeError: Cannot read properties of undefined (reading 'map')enProjectList.tsx:18. Funciona con mi cuenta, que tiene proyectos. Corrígelo para que una cuenta vacía muestre «Aún no hay proyectos», y prueba una cuenta nueva en la vista previa.
Paso 5: añade un error boundary
En React, un solo componente que falla puede desmontar toda la app, por eso un error pequeño produce una página completamente en blanco. Un error boundary es un componente que captura los errores de renderizado que tiene debajo y muestra un mensaje de respaldo.
Añade un error boundary alrededor de las rutas principales que muestre «Algo salió mal» con un botón de Recargar, y registre el error en la consola. Deja la cabecera y la navegación fuera para que sigan mostrándose.
No arregla el error, pero los visitantes ven un mensaje en lugar de una pantalla en blanco, y tú ves dónde se rompió.
Paso 6: sin errores, pero en blanco
Si la consola está limpia y los scripts se cargan:
- Revisa la pestaña Elementos. ¿Hay contenido dentro de
<div id="root">? Si lo hay, se está renderizando pero es invisible: texto blanco sobre blanco,opacity: 0,display: none, o un elemento a pantalla completa que lo tapa. - Revisa el enrutador. Si ninguna ruta coincide con la URL actual y no hay una ruta de «no encontrado», algunos enrutadores no renderizan nada. Añade una ruta catch-all que muestre una página 404.
- Revisa el punto de montaje. El código debe montarse en un elemento que exista. Si
index.htmltieneid="app"y el código buscaroot, no aparece nada (y React suele registrar un error). - Revisa las extensiones del navegador. Prueba en una ventana privada. Los bloqueadores de anuncios a veces bloquean scripts con nombres como
analyticsoads.
¿En blanco solo tras recargar una página?
Si la página de inicio funciona pero al recargar /dashboard aparece una página en blanco o un 404, el servidor no sabe que debe enviar index.html para las rutas de la app. Es un problema de fallback de enrutado, que se explica en cómo solucionar los errores 404 tras publicar.
Errores comunes
- Leer el último error en lugar del primero. La primera línea en rojo suele ser la causa.
- Configurar variables de entorno sin volver a compilar. Las variables del front end se fijan en el momento de compilar.
- Probar solo con tu propia cuenta. Los fallos con cuentas vacías son una de las causas más comunes de página en blanco.
- Dar por hecho que el despliegue funcionó. Revisa el registro de compilación antes de depurar el código.
- Culpar a la caché del navegador de todo. Una recarga forzada lo descarta en segundos; si la página sigue en blanco, es otra cosa.
Páginas en blanco en Mythex
Si la Vista previa está en blanco, primero comprueba que la app se esté ejecutando (abre Código → terminal); después pide a Mythex que inicie el servidor correcto, pulsa Actualizar en la barra de la vista previa, o usa /fix. Para una URL publicada en blanco, la documentación sugiere esperar un minuto y recargar forzando la caché, confirmar que las variables de entorno y la base de datos se configuraron antes de publicar, y revisar tu cuota de hosting. Recuerda que una app publicada es una instantánea: tras corregir algo, vuelve a publicar. Si un cambio lo provocó, Revertir a este punto en la última respuesta correcta devuelve el proyecto a su estado anterior. Consulta Solución de problemas y Solución de problemas de publicación en la documentación, y nuestra guía general sobre cómo depurar una app creada con IA.
Lista de comprobación de página en blanco
- Leíste el primer error en rojo de la Consola
- Revisaste en la pestaña Red los archivos
.js/.cssque dan 404 o devuelven HTML - La ruta base coincide con el lugar donde se sirve la app
- La compilación terminó, y la carpeta de salida de compilación es la que se publica
- Todas las variables de entorno del front end están configuradas en la compilación en vivo, y después se volvió a compilar
- El fallo está corregido, incluido para cuentas vacías y nuevas
- Hay un error boundary para que los fallos futuros muestren un mensaje
- Hay una ruta catch-all para las URLs desconocidas
- Probado tras una recarga forzada y en una ventana privada
Preguntas
¿Por qué mi app de React muestra una página en blanco?
Normalmente porque el JavaScript falló antes de dibujar nada, o porque el archivo JavaScript nunca se cargó. Abre la consola del navegador: un error en rojo te indicará cuál es, y el archivo y la línea donde ocurrió.
¿Por qué mi app funciona en local pero muestra una página en blanco tras publicarla?
Las causas más habituales son variables de entorno que nunca se configuraron para la compilación en producción, archivos JavaScript y CSS solicitados desde una ruta incorrecta (un desajuste de la ruta base), y un index.html en caché que apunta a archivos que ya no existen.
¿Qué significa «Failed to load module script»?
El navegador pidió un archivo JavaScript y recibió una página HTML en su lugar, normalmente el index.html del sitio o una página de error. La ruta del archivo es incorrecta o el archivo no existe en el servidor, así que revisa la salida de compilación y la configuración de la ruta base de la app.
¿Cómo evito que un solo error deje la página entera en blanco?
Añade un error boundary. En React, un error boundary es un componente que captura los errores de renderizado en la parte de la página que tiene debajo y muestra un mensaje de respaldo en lugar de desmontar todo.