Problemas con la CLI

Tus credenciales guardadas faltan o el token de actualización ya no es válido.

Solución: Ejecuta jamdesk login para iniciar una sesión nueva. Esto reemplaza lo que hubiera en ~/.jamdeskrc.

Si el error vuelve a aparecer inmediatamente después de iniciar sesión, comprueba que ~/.jamdeskrc se haya escrito:

cat ~/.jamdeskrc

El archivo debe contener un objeto auth con refreshToken, email y uid. Si está vacío o falta, tu directorio home puede tener problemas de permisos.

La CLI inicia un servidor local en el puerto 9876 para recibir el callback de autenticación desde tu navegador. Si el callback nunca llega, el inicio de sesión agota el tiempo de espera después de 2 minutos.

Causas comunes:

• Un firewall está bloqueando el servidor local
• La pestaña del navegador se cerró antes de completar la autenticación
• El puerto 9876 está ocupado (la CLI elige otro puerto automáticamente, pero la URL debe coincidir)

Solución: Copia la URL impresa en la terminal y ábrela manualmente. Comprueba que el número de puerto en la URL coincida con el que la CLI está escuchando.

Es normal en entornos sin interfaz gráfica (sesiones SSH, contenedores Docker, ejecutores de CI). La URL de inicio de sesión siempre se imprime en la terminal, incluso cuando no hay navegador disponible.

Cópiala y ábrela en cualquier navegador que pueda llegar a tu máquina en el puerto de callback.

Cambiar tu contraseña de Jamdesk invalida todos los tokens de actualización existentes. La CLI detecta esto (TOKEN_EXPIRED o INVALID_REFRESH_TOKEN) y borra la autenticación guardada automáticamente.

Ejecuta jamdesk login de nuevo.

Solo se ejecuta un build a la vez por proyecto. La CLI devuelve este error (código BUILD_IN_PROGRESS) cuando hay un build en cola o en ejecución.

Solución: Espera a que termine el build actual. Revisa Deployments en el dashboard para ver el estado. Si un build parece estancado, pídele al propietario del proyecto que revise el dashboard.

No hay docs.json en el directorio actual, o tiene errores de sintaxis JSON.

Solución:

1. Asegúrate de estar en el directorio correcto: ls docs.json
2. Ejecuta jamdesk validate para ver detalles específicos del error
3. Revisa si faltan comas, hay corchetes sin cerrar o comas finales (la CLI usa JSON, no JSON5, para docs.json)

Tu tarball comprimido supera el límite de 100 MB. Todo lo que no esté excluido por .gitignore o la lista de exclusión integrada se empaqueta.

Solución: Revisa qué se está incluyendo. Causas comunes: archivos de video, PDFs grandes, imágenes sin comprimir, volcados de datos. Agrégalos a .gitignore.

Siempre excluidos sin importar .gitignore: .git, node_modules, .next, .env*, *.pem, *.key, credentials.json, .DS_Store.

Todos los archivos coincidieron con un patrón de exclusión. No queda nada para subir.

Solución: Revisa tu .gitignore. Si está bloqueando archivos MDX o docs.json, la CLI no tiene con qué trabajar.

Ya sea que el projectId en docs.json no coincida con ningún proyecto de tu cuenta, o que no seas miembro de ese proyecto.

Solución:

• Elimina el campo projectId de docs.json y vuelve a ejecutar jamdesk deploy para elegir un proyecto nuevo
• Verifica que hayas iniciado sesión con la cuenta correcta: jamdesk whoami
• Revisa la membresía del proyecto en el dashboard

El estado del build se sondea cada 2 segundos. Si tu red es inestable, se toleran hasta 3 fallos de sondeo consecutivos antes de que la CLI se rinda.

Solución: Presiona Ctrl+C. El build sigue ejecutándose en segundo plano. Revisa el dashboard para ver el estado. Se imprime un enlace al salir.

La subida se completó, pero el build en sí falló. Verás el error del build service en tu terminal.

Solución: Revisa el registro del build en el dashboard, en Deployments. Causas comunes: errores de sintaxis MDX, páginas faltantes referenciadas en la navegación, specs de OpenAPI inválidas. Ejecuta jamdesk validate localmente para detectar esto antes de desplegar.

Verás una advertencia cuando los archivos parezcan secretos (.env, *.pem, *.key, credentials.json, archivos que empiecen con secret). Esto es una advertencia, no un bloqueo.

Solución: Agrega los archivos a .gitignore para excluirlos de las subidas. Si son intencionales (por ejemplo, archivos de clave de ejemplo en tu documentación), ignora la advertencia.

Varias cosas pueden impedir el inicio.

Prueba en orden:

1. jamdesk doctor para comprobar la versión de Node.js (se requiere v20+) y el entorno
2. jamdesk clean para borrar las dependencias en caché
3. jamdesk dev --verbose para obtener información detallada del error
4. jamdesk dev --clean para borrar la caché de build antes de iniciar

La CLI prueba 10 puertos consecutivos comenzando desde el puerto solicitado (por defecto 3000). Si los 10 están ocupados, falla.

Solución:

# Find what's using the port
lsof -i :3000

# Pick a different port
jamdesk dev --port 3001

Para establecer un valor predeterminado permanente, agrega "defaultPort": 3001 a tu archivo ~/.jamdeskrc. No sobrescribas el archivo; puede contener tus credenciales de autenticación.

Si el servidor de desarrollo se cierra a mitad de la compilación (cierre forzado, fallo del sistema), la caché .next puede corromperse. Verás errores de "corrupted database" o de pánico en el siguiente inicio.

Solución:

jamdesk dev --clean

Esto borra el directorio .next y comienza de cero.

La primera vez que se ejecuta jamdesk dev se instalan dependencias de runtime en ~/.jamdesk/node_modules. Esto ocurre una sola vez y puede tardar de 1 a 2 minutos en conexiones lentas.

Las ejecuciones posteriores omiten la instalación a menos que cambie la versión de la CLI.

Si npm install se cuelga durante la primera ejecución, hay un tiempo de espera de 5 minutos.

Solución:

1. Comprueba tu conexión a internet
2. jamdesk clean para borrar instalaciones parciales
3. Vuelve a intentarlo
4. Si npm es consistentemente lento, revisa la configuración de tu registro de npm: npm config get registry

MDX trata < como un abridor de etiqueta JSX. Escribir <50% provoca un error de análisis.

Solución: Escápalo con < o reescríbelo. Ejecuta jamdesk validate para obtener números de línea y sugerencias.

jamdesk broken-links encontró enlaces internos que apuntan a páginas que no existen.

Solución: Revisa las rutas de archivo. Errores comunes: mayúsculas/minúsculas incorrectas (Quickstart frente a quickstart), incluir la extensión .mdx, o rutas antiguas que fueron renombradas.

La CLI sugiere correcciones para coincidencias cercanas (dentro de 3 caracteres de un error tipográfico).

Corrígelos automáticamente. Si un enlace roto tiene un destino correcto no ambiguo (un ancla con error tipográfico o una desviación de ancla entre idiomas), ejecuta jamdesk fix --dry-run para previsualizar los cambios, y luego jamdesk fix para aplicarlos. Solo reescribe enlaces cuyo ancla corregida sea un encabezado real en la página de destino; los casos ambiguos se dejan para que los corrijas manualmente. Consulta Corrección automática de enlaces rotos.

La CLI valida las specs de OpenAPI referenciadas en docs.json. Los fallos incluyen referencias $ref inválidas, campos requeridos faltantes o errores de sintaxis.

Solución: Ejecuta jamdesk openapi-check path/to/spec.yaml para obtener información detallada. Usa el Swagger Editor para depurar specs complejas.

No está instalado globalmente, o tu shell no puede encontrar el binario.

Solución:

npm install -g jamdesk

Si lo instalaste con curl, asegúrate de que ~/.jamdesk/bin esté en tu PATH.

Se necesita acceso de escritura para ~/.jamdesk (caché) y ~/.jamdeskrc (credenciales).

Solución:

ls -la ~/.jamdesk ~/.jamdeskrc
sudo chown -R $(whoami) ~/.jamdesk ~/.jamdeskrc

jamdesk update envuelve npm install -g jamdesk@latest. Si npm tiene problemas de permisos o el registro no está disponible, falla.

Solución: Actualiza manualmente:

npm install -g jamdesk@latest

Si eso también falla, revisa npm config get registry e intenta sudo npm install -g jamdesk@latest.