Resolución de problemas

Los síntomas se agrupan según dónde aparecen en el camino de la instalación a la exportación, con los fallos más comunes de los recién llegados primero. Cada entrada nombra la causa y el comando de solución.

🚧 Instalación y entorno

uv sync falla

Causa: Python 3.12 o más reciente no está en el PATH, o falta uv. Solución: Confirma la versión de Python y vuelve a ejecutar:

uv sync --all-extras --group dev

Si falta uv, instálalo desde las instrucciones oficiales del paquete de Astral, abre una nueva shell y vuelve a ejecutar el comando.

El instalador informa de un prerrequisito faltante

Causa: Los scripts de instalación requieren git y uv en el PATH. Solución: Instala el prerrequisito nombrado y vuelve a ejecutar el mismo comando de instalación. Define DISPATCHATLAS_HOME antes de volver a ejecutar cuando el checkout deba residir fuera del directorio de datos de usuario por defecto.

La actualización informa de cambios pero no los aplica

Causa: Las comprobaciones de actualización son de solo lectura por defecto. Solución: Define DISPATCHATLAS_REF con una etiqueta de versión o un SHA de commit completo de 40 caracteres, luego aplica la actualización por checkout desacoplado de forma explícita:

$env:DISPATCHATLAS_REF = "<release-tag>"
.\scripts\installer\update.ps1 -Apply

export DISPATCHATLAS_REF="<release-tag>"
scripts/installer/update.sh --apply

La desinstalación rechaza un destino

Causa: Los scripts de desinstalación rechazan rutas vacías, raíces del sistema de archivos, directorios de inicio y directorios sin el centinela del espacio de trabajo de DispatchAtlas. Solución: Define DISPATCHATLAS_HOME con la ruta del checkout instalado y vuelve a ejecutar el comando de desinstalación.

📦 Importaciones

ModuleNotFoundError: No module named 'dispatchatlas'

Causa: El espacio de trabajo no está sincronizado, o el script se ejecuta bajo un intérprete de Python fuera del entorno del proyecto. Solución: Desde la raíz del repositorio, sincroniza y ejecuta los scripts a través de uv para que el entorno del proyecto esté activo:

uv sync --all-extras --group dev
uv run python your-script.py

MissingOptionalDependencyError al crear un solver

Causa: Los backends opcionales pesados (solvers exactos, estimadores de aprendizaje) permanecen detrás de extras y se sondean en tiempo de ejecución, nunca se importan durante la importación del paquete. El error nombra el extra faltante, su propósito y cualquier nota de licencia. Solución: Instala el extra nombrado (por ejemplo exact, exact-commercial, o learning) o selecciona un solver cuyo backend esté presente. Las declaraciones de dependencias de los solvers se listan en sistema de solvers.

🧪 Configuración y ejecución de campañas

CampaignConfigError al validar una campaña

Causa: Un campo de configuración no supera la validación — un id vacío, una semilla o presupuesto no positivos, nombres de protocolo de parada duplicados, o una lista vacía de benchmarks, solvers u objetivos. El error lleva la ruta del campo que falla. Solución: Corrige el campo nombrado. La página del motor de campañas documenta cada bloque de configuración, y experiments/configs/smoke-pilot.json es un ejemplo de trabajo completo:

uv run dispatchatlas-lab validate --config experiments/configs/smoke-pilot.json

KeyError al obtener un problema de benchmark

Causa: El id del problema no está en el catálogo del proveedor, o se pasó una cadena simple donde se espera un ProblemId. Solución: Envuelve el id (provider.get_problem(ProblemId("smoke-job-shop-0"))) y lista primero los ids disponibles con provider.list_problem_ids() — consulta los tutoriales.

La campaña completa se niega a ejecutarse

Causa: Una campaña en la etapa full falla en cerrado con full-campaign execution requires statistical design approval hasta que esa aprobación se registre en la configuración. Solución: Ejecuta en la etapa smoke o pilot para comprobaciones locales, o registra la aprobación del diseño estadístico según preparación de la versión antes de habilitar la ejecución completa.

La reanudación replanifica en lugar de omitir ejecuciones completadas

Causa: El punto de control en .checkpoints/{campaign_id}.json está protegido por un hash de configuración; cualquier cambio de configuración lo invalida en lugar de reutilizarlo en silencio. Solución: Mantén la configuración sin cambios para reanudar, o acepta un plan nuevo bajo la configuración cambiada. El contrato del espacio de trabajo se describe en campañas reproducibles.

📤 Exportaciones, informes y el sitio

La exportación de análisis informa de un punto de control faltante

Causa: El comando dispatchatlas export espera un directorio de campaña completado con checkpoint.json, plan.json, environment.json y registros de resultados. Solución: Apunta --campaign-dir al directorio de resultados de la campaña en lugar de a su padre, o vuelve a ejecutar la campaña:

uv run dispatchatlas export `
  --campaign-dir .\experiments\results\smoke-pilot `
  --target-dir .\exports\smoke-pilot `
  --authorized-output-root .\exports `
  --tier core

Si --target-dir está fuera del directorio de trabajo actual, pasa un --authorized-output-root explícito que contenga el destino.

La validación de datos del portal falla

Causa: Los activos del sitio estático están desfasados respecto a la exportación de resultados del portal. Solución: Regenera los activos estáticos. El comando lee la exportación de resultados filtrada por divulgación y comprometida en exports/portal-results.json por defecto, por lo que se ejecuta sin argumentos:

uv run python tools/build_site_assets.py

Pasa --result-source para publicar una exportación portal-results.json filtrada por divulgación diferente:

uv run python tools/build_site_assets.py --result-source .\path\to\portal-results.json

Si el comando informa dispatchatlas site-assets: error, comprueba que --result-source (o el exports/portal-results.json por defecto) apunte a un archivo portal-results.json existente generado por la ruta de exportación de análisis.

La puerta de redacción del portal falla

Causa: Un token que no pertenece a la superficie pública llegó a los datos del portal, por lo que la compilación falla en cerrado para mantener la cara publicada leyéndose como un kit genérico de optimización de planificación. Solución: El error lista cada artefacto infractor, ruta de campo y token. Redacta el campo infractor en el constructor que emite ese artefacto (bajo tools/portal_contract.py o su evidencia de origen) para que solo evidencia derivada segura para el público llegue a los datos del portal, luego regenera:

uv run python tools/build_site_assets.py

Este fallo es distinto de una exportación de portal faltante: pasar un --result-source diferente no lo soluciona — el token infractor debe eliminarse en su origen.

La compilación del sitio no encuentra una página

Solución: Ejecuta las pruebas de contrato del sitio y la compilación de la documentación:

uv run pytest tests/site
npm --prefix site run build
npm --prefix site run check

Falta un solver en las recomendaciones

Causa: La selección filtra por metadatos. Solución: Comprueba en los metadatos del solver el soporte de objetivos, las etiquetas de capacidad requeridas, el estado de dependencias opcionales y la visibilidad por nivel de evidencia en sistema de solvers.

¿Sigues atascado? Consulta las preguntas frecuentes o abre una incidencia en el repositorio de GitHub.