save-url-main/documentacion/08_TROUBLESHOOTING.md

Troubleshooting

1) El DAG no aparece o falla al importarse

Síntomas

• Airflow muestra “ImportError” o el DAG no se lista.

Causas comunes

• La ruta '/opt/airflow/dags/save_url_ftp' no existe dentro del contenedor.
• SaveUrl.py no está en esa carpeta (o tiene otro nombre).
• Dependencias no instaladas en el entorno del worker (ej. pyodbc, kafka).

Acciones

• Verifica que existan los archivos:
  • /opt/airflow/dags/save_url_ftp/dag_save_url_ftp.py
  • /opt/airflow/dags/save_url_ftp/SaveUrl.py
• Revisa el scheduler logs por import errors.

2) Error conectando al FTP

Síntomas

• ❌ FTP | ... en logs
• notificación por webhook con “Error leyendo FTP folder ...”

Causas comunes

• Credenciales incorrectas (FTP_000oqta_USER / FTP_000oqta_PASSWORD)
• Host incorrecto (FTP_000oqta_SERVER)
• Firewall / DNS / ruteo
• La carpeta del mes no existe (<name_folder><MM>)

Acciones

• Probar conectividad desde el mismo runtime (worker) hacia el host FTP.
• Confirmar que FTP_BASE_PATH + code_folder existe en el servidor.
• Verificar si el servidor cambió estructura para 2027/otro año (porque FTP_BASE_PATH incluye 2026).

3) Error leyendo SQL Server

Síntomas

• ❌ SQL | ... en logs
• webhook “Error leyendo URLs ...”

Causas comunes

• Driver ODBC faltante en el worker (ODBC Driver 18 for SQL Server)
• Credenciales inválidas o permisos insuficientes
• SQL Server inaccesible desde la red del worker
• Tabla URL_FTP inexistente o en otro schema/db esperado

Acciones

• Verificar instalación del driver ODBC en el contenedor/host.
• Validar que el usuario tenga SELECT sobre URL_FTP.
• Confirmar nombre de la base de datos: se toma de INFORMATIONS (ej. glm_pmi, IS001).

4) Error insertando (schema/constraints)

Síntomas

• ❌ INSERT | ... en logs
• webhook “Error insertando URLs ...”

Causas comunes

• La tabla tiene columnas NOT NULL sin default que el dict no provee.
• Tipos incompatibles (ej. Date espera datetime pero recibe string).
• Restricción UNIQUE (por IDcodigo, URL, u otra combinación) que el código no contempla.

Acciones

• Revisar definición de URL_FTP y confirmar que acepta las columnas:
  • Folder, Date, IDcodigo, ObjectCode, TaskName, URL
• Confirmar tipos: el código inserta strings.
• Si existe una columna “ExportDate”, el código NO la inserta (la excluye si aparece en dict).

5) No inserta nada, pero debería

Síntomas

• A insertar: 0 repetidamente, aunque hay archivos nuevos en FTP.

Causas comunes

• IDcodigo se parsea mal (mismo valor para distintos archivos) por cambios de naming.
• La consulta SQL Folder LIKE %code_folder% trae más registros de los necesarios y “tapa” IDs.
• El FTP lista rutas que no cumplen el patrón y el parse genera IDs inesperados.

Acciones

• Tomar una URL real del FTP y revisar manualmente el parsing:
  • ¿contiene _{YYYY}-{MM}?
  • ¿contiene el identity_id correcto?
  • ¿IDcodigo de 24 chars es correcto?
• Comparar un IDcodigo “nuevo” con los existentes en SQL.

6) Kafka no recibe logs

Síntomas

• Logs de Airflow muestran fallos de Kafka o no hay eventos en executions_logs.

Causas comunes

• BOOTSTRAP_SERVERS_DOCKER incorrecto para el runtime del worker.
• KAFKA_USE_SSL=True pero faltan variables de entorno SECURITY_PROTOCOL, SASL_*, SSL_CAFILE, etc.
• Certificados/rutas inválidas dentro del contenedor.

Acciones

• Validar conectividad al broker desde el contenedor/worker.
• Si SSL/SASL: asegurar que las variables están definidas como env vars del proceso.

7) Webhook no notifica

Síntomas

• Se ve el error en logs pero no llega alerta.

Causas comunes

• WEBHOOK_URL_NOTIFICATION no definido o es inválido.
• Endpoint requiere auth/cabeceras adicionales (el código no las envía).
• Restricciones de red del worker.

Acciones

• Probar un POST manual al webhook desde el mismo entorno.
• Revisar respuesta HTTP (4xx/5xx) en logs si se captura (actualmente no se valida el status code).