NAÏA — Déboguer une erreur

NAÏA diagnostique les erreurs Noria et propose une solution concrète avec le code corrigé.

Comment l'utiliser

Charge le prompt 3_debug_erreur.prompt.md
Colle le message d'erreur complet (avec la stack trace si disponible)
NAÏA identifie la cause et propose une solution avec le code corrigé

Référence des erreurs

Erreurs de compilation

Erreur	Cause	Solution
`CompilationError: undefined variable 'x'`	Variable Jinja2 `{{ x }}` non définie	Ajouter `x:` dans `params:` ou vérifier l'orthographe
`CompilationError: macro not found`	Macro appelée dans le SQL mais absente	Vérifier `sql/macros/` ou utiliser une macro intégrée
`ConfigError: merge_key required`	`output_write: merge` sans `merge_key`	Ajouter `merge_key: [col_id]`
`ConfigError: scd2_key required`	`output_write: scd2` sans `scd2_key`	Ajouter `scd2_key: [col_id]`
`ConfigError: seed_file required`	`type: seed` sans `seed_file`	Ajouter `seed_file: data/mon_fichier.csv`
`DependencyError: cycle detected`	Cycle dans `needs`	Visualiser avec `noria dag` et corriger
`DependencyError: unknown task 'x'`	`needs:` référence une tâche inexistante	Vérifier le nom de la tâche

Erreurs d'exécution

Erreur	Cause	Solution
`ExecutionError: safe_replace guard on 'stats': query returned 0 row(s) but safe_replace_min_rows=1`	La requête SQL renvoie moins de lignes que le seuil	Vérifier la requête ou baisser `safe_replace_min_rows`
`ExecutionError: assert FAILED — 3 violation(s)`	Assertion qualité : des lignes de violation ont été retournées	Vérifier les données, les violations sont dans le log
`ExecutionError: Freshness check FAILED`	La table source est plus ancienne que `max_hours`	Attendre l'alimentation de la source ou ajuster `max_hours`
`TaskError: timed out after 300s`	La tâche dépasse le `timeout:` configuré	Augmenter `timeout:` ou optimiser la requête
`Seed file not found: data/ref.csv`	`seed_file:` pointe vers un fichier absent	Vérifier le chemin relatif depuis la racine du projet

Erreurs de connexion

Erreur	Cause	Solution
`OperationalError: could not connect to server`	PostgreSQL inaccessible	Vérifier `host`, `port`, credentials dans `.noria/.env`
`google.auth.exceptions.DefaultCredentialsError`	Application Default Credentials absentes (BigQuery)	Exécuter `gcloud auth application-default login`
`duckdb.IOException: Could not open file`	Fichier DuckDB verrouillé par un autre process	Fermer les autres connexions (DBeaver, notebook, etc.)

Exemples de diagnostic NAÏA

Exemple 1 — safe_replace guard

Erreur :

ExecutionError: safe_replace guard on 'monthly_stats': query returned 0 row(s)
but safe_replace_min_rows=1000 — aborting to protect existing data

NAÏA diagnostique :

La requête SQL de monthly_stats ne retourne aucune ligne. Causes possibles : 1. La table source est vide (tâche précédente a échoué silencieusement) 2. Un filtre de date trop restrictif élimine toutes les lignes 3. Une jointure trop sélective produit un résultat vide

Commande de diagnostic :

noria compile --task monthly_stats   # voir le SQL compilé
noria run --task monthly_stats --dry-run  # compter les lignes sans écrire

Solution :

# Option 1 — baisser le seuil si les données sont légitimement peu nombreuses
monthly_stats:
  output_write: safe_replace
  safe_replace_min_rows: 10   # au lieu de 1000

# Option 2 — supprimer le garde-fou si replace total est acceptable
monthly_stats:
  output_write: replace

Exemple 2 — CompilationError variable non définie

Erreur :

CompilationError: undefined variable 'date_debut' in sql/filtrage.sql (line 5)

SQL fautif :

WHERE date_commande >= '{{ date_debut }}'

NAÏA diagnostique : date_debut n'est pas déclaré dans params:.

Solution :

nodes:
  filtrage:
    sql: sql/filtrage.sql
    params:
      date_debut: "2024-01-01"   # ajouter le paramètre manquant

Ou passer la valeur à l'exécution :

noria run --params date_debut=2024-01-01

Exemple 3 — Assertion échouée

Erreur :

ExecutionError: assert FAILED — task 'assert_positive_revenue' returned 3 violation(s)

Sample rows:
  client_id | ca_total | motif
  C001      | -142.50  | CA négatif interdit
  C089      | -23.00   | CA négatif interdit
  C234      | -5.75    | CA négatif interdit

NAÏA diagnostique : 3 clients ont un CA négatif dans la table customer_stats. Ce n'est pas un bug Noria — c'est un vrai problème de données.

Démarche de résolution :

-- Investiguer la source des avoirs
SELECT client_id, date_commande, montant_ht, type_piece
FROM customer_stats
WHERE client_id IN ('C001', 'C089', 'C234')
ORDER BY date_commande

Si le comportement est attendu :

assert_positive_revenue:
  type: assert
  sql: sql/assert_positive_revenue.sql
  soft_fail: true   # log un WARNING sans bloquer le pipeline

Exemple 4 — Cycle dans les dépendances

Erreur :

DependencyError: cycle detected — [stats → rapport → stats]

NAÏA diagnostique : rapport dépend de stats, et stats dépend de rapport — c'est impossible à exécuter.

Diagnostic visuel :

noria dag --format ascii

Solution : Identifier quelle dépendance est incorrecte et la supprimer.

Inspecter le SQL compilé

Avant de soumettre une erreur à NAÏA, utilise noria compile pour voir le SQL réel après résolution des variables et des macros :

# SQL compilé d'une tâche
noria compile --task monthly_stats

# SQL compilé avec des params spécifiques
noria compile --task monthly_stats --params schema=prod

Cela aide à identifier : - Les variables non résolues - Les macros qui génèrent du SQL inattendu - Les filtres de date qui éliminent trop de données

Activer les logs détaillés

noria run --verbose                     # logs DEBUG dans le terminal
noria run --log-file noria_debug.log    # écrire les logs dans un fichier

Les logs détaillés montrent : - Le SQL exact exécuté sur la base - Les durées d'exécution par tâche - Les tentatives de retry - Les résultats des freshness checks