For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /es/docs/web/troubleshooting.md (or send Accept: text/markdown).
Solución de problemas
Diagnostica los problemas de configuración en el límite que realmente falló.
Configuración y ajustes
Antes de cualquier paso, lea Antes de comenzar y Conceptos básicos del terminal. Estas instrucciones suponen que abrió el monorepo supastack completo en VS Code; su paquete raíz.json marca la raíz del repositorio. En los comandos pnpm, un paquete de espacio de trabajo es una aplicación o una carpeta de código compartido; En el producto, un espacio de trabajo es el contenedor de datos y el límite de seguridad de un equipo. corepack pnpm --filter ... selecciona un paquete del monorepo mientras los comandos se ejecutan desde su raíz. Si abrió solo una carpeta sincronizada para dispositivos móviles o de escritorio, no contiene el backend web, la configuración de Docker ni los scripts raíz: ejecute el backend desde este monorepo o un servidor alojado accesible y use los propios scripts de la carpeta de la plataforma. Una variable de entorno es una configuración con nombre almacenada en un archivo .env local o en su panel de hosting; reinicie la aplicación correspondiente después de cambiarla y mantenga los secretos del servidor fuera de los valores NEXT_PUBLIC_ y EXPO_PUBLIC_.
1. Copie la primera línea de error útil y el comando que la produjo; no pegue valores secretos.
2. Desde la raíz del repositorio, ejecute corepack pnpm --filter @supastack/web typecheck para errores de tipo web, o corepack pnpm test para la suite automatizada.
3. Para un problema del navegador, inicie Web con corepack pnpm --filter @supastack/web dev y reprodúzcalo en http://localhost:3000. Esperado: puede saber si el error está en la configuración, el código, la base de datos, el proveedor o el navegador antes de cambiar la configuración.
Lee el comando fallido y el primer error pertinente antes de cambiar la configuración. Determina si falló la instalación de dependencias, la compilación, la validación del entorno, el acceso a la base de datos, el despacho del proveedor o el comportamiento del navegador.
corepack pnpm --filter @supastack/web typecheck
corepack pnpm --filter @supastack/web build
corepack pnpm testComandos para copiar
Siga los comentarios para ver en qué carpeta se ejecuta un comando. Si dos terminales están etiquetados, abra dos ventanas de terminal y mantenga el primer comando ejecutándose mientras usa el segundo.
corepack pnpm --filter @supastack/web typecheck
corepack pnpm testErrores de la primera ejecución, descifrados
La primera ejecución falla de un pequeño conjunto de formas. Relaciona la primera línea de error en rojo con una fila — los errores posteriores suelen ser consecuencias del primero, así que corrige el de arriba antes que cualquier otro.
| Síntoma | Causa probable | Primera corrección |
|---|---|---|
| «node, corepack o pnpm no se reconoce» / command not found | La herramienta no está instalada, o la terminal se abrió antes de que terminara la instalación | Instálala (o vuelve a abrir la terminal) y reintenta node --version |
| No se encontró package.json / ENOENT package.json | La terminal está en la carpeta equivocada | Haz cd a la raíz del repositorio — la carpeta que contiene package.json — y reintenta |
| EADDRINUSE / el puerto 3000 ya está en uso | Otro servidor de desarrollo aún ocupa el puerto | Encuentra la terminal de ese servidor y pulsa Ctrl + C, luego vuelve a empezar |
| ECONNREFUSED a localhost:5432 o un error de conexión a la base de datos | Postgres no está en ejecución | Ejecuta docker compose up -d postgres, espera a que indique healthy y reintenta |
| Error de validación de entorno que nombra una clave ausente | Falta apps/web/.env.local o tiene un valor requerido vacío | Copia la clave nombrada desde .env.example, dale un valor, guarda y reinicia el servidor |
| Faltan corepack o pnpm después de corepack enable | Ningún shim de pnpm está en PATH | Usa corepack pnpm ... directamente — nunca necesita un shim; en Windows usa corepack.cmd |
| PowerShell dice que un script .ps1 no puede ejecutarse / está bloqueado | La política de scripts de PowerShell bloquea el shim | Usa la forma .cmd — corepack.cmd pnpm install — sin cambiar la política |
Flujo de implementación
Si falta acceso a la API, verifica que el servidor esté activo y que el origen configurado coincida con el del cliente. Si no hay opciones de IA disponibles, inspecciona AI_MODEL_POLICY y las filas habilitadas del catálogo. Para una tarea encolada cuyo estado es incierto, usa el flujo de recuperación guardada en vez de iniciar otro envío.
Ante problemas de diseño del navegador, inspecciona los estilos calculados y reproduce la ventana gráfica exacta. Los tokens del chrome del producto están en app-theme.css (los paquetes proceden de catalog.ts); el bloqueo de marca de marketing está en theme.css. Las anulaciones de componentes todavía pueden prevalecer por especificidad. Comprueba el radio renderizado, no solo la declaración del token.
Verificación y solución de problemas
Si la página está en :3001, abra :3000 para la aplicación web; :3001 pertenece al servidor apps/docs independiente. Si una prueba solicita acceso a la base de datos, utilice una base de datos de desarrollo aislada y verifique ambas ubicaciones de .env. Si el mismo error persiste, incluya el comando y la primera línea de error desinfectada cuando solicite ayuda; nunca deshabilite las comprobaciones de acceso ni imprima secretos en los registros.
No soluciones una comprobación fallida deshabilitando la autorización, registrando secretos o dando por aprobadas comprobaciones de infraestructura omitidas. Crea una reproducción pequeña y reúne la configuración pertinente que no contenga secretos. Tras la corrección, vuelve a ejecutar la comprobación fallida y después las pruebas de regresión afectadas.