Débogage des Workflows

Traduction assistée par IA - en savoir plus et suggérer des améliorations

Le débogage est une compétence essentielle qui peut vous faire gagner des heures de frustration et vous aider à devenir un·e développeur·se Nextflow plus efficace. Tout au long de votre carrière, en particulier lorsque vous débutez, vous rencontrerez des bugs lors de la construction et de la maintenance de vos workflows. L'apprentissage d'approches de débogage systématiques vous aidera à identifier et à résoudre les problèmes rapidement.

Objectifs d'apprentissage

Dans cette quête annexe, nous explorerons les techniques de débogage systématiques pour les workflows Nextflow :

• Débogage des erreurs de syntaxe : Utilisation efficace des fonctionnalités de l'IDE et des messages d'erreur de Nextflow
• Débogage des canaux : Diagnostic des problèmes de flux de données et de structure des canaux
• Débogage des processus : Investigation des échecs d'exécution et des problèmes de ressources
• Outils de débogage intégrés : Exploitation du mode preview, de l'exécution stub et des répertoires de travail de Nextflow
• Approches systématiques : Une méthodologie en quatre phases pour un débogage efficace

À la fin, vous disposerez d'une méthodologie de débogage robuste qui transforme les messages d'erreur frustrants en feuilles de route claires vers les solutions.

Prérequis

Avant d'entreprendre cette quête annexe, vous devez :

• Avoir terminé le tutoriel Hello Nextflow ou un cours équivalent pour débutants.
• Être à l'aise avec les concepts et mécanismes de base de Nextflow (processus, canaux, opérateurs)

Optionnel : Nous recommandons de terminer d'abord la quête annexe Fonctionnalités IDE pour le Développement Nextflow. Celle-ci couvre de manière exhaustive les fonctionnalités de l'IDE qui supportent le débogage (coloration syntaxique, détection d'erreurs, etc.), que nous utiliserons intensivement ici.

---

0. Commencer

Ouvrir l'espace de code de formation

Si vous ne l'avez pas encore fait, assurez-vous d'ouvrir l'environnement de formation comme décrit dans la Configuration de l'Environnement.

Se déplacer dans le répertoire du projet

Déplaçons-nous dans le répertoire où se trouvent les fichiers pour ce tutoriel.

cd side-quests/debugging

Vous pouvez configurer VSCode pour se concentrer sur ce répertoire :

code .

Examiner le matériel

Vous trouverez un ensemble d'exemples de workflows avec divers types de bugs que nous utiliserons pour la pratique :

Contenu du répertoire

.
├── bad_bash_var.nf
├── bad_channel_shape.nf
├── bad_channel_shape_viewed_debug.nf
├── bad_channel_shape_viewed.nf
├── bad_number_inputs.nf
├── badpractice_syntax.nf
├── bad_resources.nf
├── bad_syntax.nf
├── buggy_workflow.nf
├── data
│   ├── sample_001.fastq.gz
│   ├── sample_002.fastq.gz
│   ├── sample_003.fastq.gz
│   ├── sample_004.fastq.gz
│   ├── sample_005.fastq.gz
│   └── sample_data.csv
├── exhausted.nf
├── invalid_process.nf
├── missing_output.nf
├── missing_software.nf
├── missing_software_with_stub.nf
├── nextflow.config
└── no_such_var.nf

Ces fichiers représentent des scénarios de débogage courants que vous rencontrerez dans le développement en conditions réelles.

Examiner l'exercice

Votre défi est d'exécuter chaque workflow, d'identifier la ou les erreurs, et de les corriger.

Pour chaque workflow bugué :

1. Exécuter le workflow et observer l'erreur
2. Analyser le message d'erreur : que vous dit Nextflow ?
3. Localiser le problème dans le code en utilisant les indices fournis
4. Corriger le bug et vérifier que votre solution fonctionne
5. Réinitialiser le fichier avant de passer à la section suivante (utilisez git checkout <filename>)

Les exercices progressent des erreurs de syntaxe simples vers des problèmes d'exécution plus subtils. Les solutions sont discutées en ligne, mais essayez de résoudre chaque problème vous-même avant de lire la suite.

Liste de vérification de préparation

Pensez-vous être prêt·e à vous lancer ?

• Je comprends l'objectif de ce cours et ses prérequis
• Mon espace de code est opérationnel
• J'ai défini mon répertoire de travail de manière appropriée
• Je comprends l'exercice

Si vous pouvez cocher toutes les cases, vous êtes prêt·e à commencer.

---

1. Erreurs de Syntaxe

Les erreurs de syntaxe sont le type d'erreur le plus courant que vous rencontrerez lors de l'écriture de code Nextflow. Elles se produisent lorsque le code ne se conforme pas aux règles de syntaxe attendues du DSL Nextflow. Ces erreurs empêchent votre workflow de s'exécuter du tout, il est donc important d'apprendre à les identifier et à les corriger rapidement.

1.1. Accolades manquantes

L'une des erreurs de syntaxe les plus courantes, et parfois l'une des plus complexes à déboguer, est les crochets manquants ou mal appariés.

Commençons par un exemple pratique.

Exécuter le pipeline

nextflow run bad_syntax.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `bad_syntax.nf` [stupefied_bhabha] DSL2 - revision: ca6327fad2

Error bad_syntax.nf:24:1: Unexpected input: '<EOF>'

ERROR ~ Script compilation failed

 -- Check '.nextflow.log' file for details

Éléments clés des messages d'erreur de syntaxe :

• Fichier et emplacement : Indique quel fichier et quelle ligne/colonne contiennent l'erreur (bad_syntax.nf:24:1)
• Description de l'erreur : Explique ce que l'analyseur a trouvé qu'il n'attendait pas (Unexpected input: '<EOF>')
• Indicateur EOF : Le message <EOF> (End Of File) indique que l'analyseur a atteint la fin du fichier en attendant toujours plus de contenu - un signe classique d'accolades non fermées

Vérifier le code

Maintenant, examinons bad_syntax.nf pour comprendre ce qui cause l'erreur :

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
    val sample_name

    output:
    path "${sample_name}_output.txt"

    script:
    """
    echo "Processing ${sample_name}" > ${sample_name}_output.txt
    """
// Accolade fermante manquante pour le processus

workflow {

    // Crée un canal d'entrée
    input_ch = channel.of('sample1', 'sample2', 'sample3')

    // Appelle le processus avec le canal d'entrée
    PROCESS_FILES(input_ch)
}

Pour les besoins de cet exemple, nous avons laissé un commentaire pour vous montrer où se trouve l'erreur. L'extension VSCode Nextflow devrait également vous donner quelques indices sur ce qui pourrait ne pas aller, en mettant l'accolade mal appariée en rouge et en soulignant la fin prématurée du fichier :

Stratégie de débogage pour les erreurs d'accolades :

1. Utilisez la correspondance d'accolades de VS Code (placez le curseur à côté d'une accolade)
2. Vérifiez le panneau Problèmes pour les messages liés aux accolades
3. Assurez-vous que chaque { d'ouverture a un } de fermeture correspondant

Corriger le code

Remplacez le commentaire par l'accolade fermante manquante :

AprèsAvant

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
    val sample_name

    output:
    path "${sample_name}_output.txt"

    script:
    """
    echo "Processing ${sample_name}" > ${sample_name}_output.txt
    """
}  // Ajoute l'accolade fermante manquante

workflow {

    // Crée un canal d'entrée
    input_ch = channel.of('sample1', 'sample2', 'sample3')

    // Appelle le processus avec le canal d'entrée
    PROCESS_FILES(input_ch)
}

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
    val sample_name

    output:
    path "${sample_name}_output.txt"

    script:
    """
    echo "Processing ${sample_name}" > ${sample_name}_output.txt
    """
// Accolade fermante manquante pour le processus

workflow {

    // Crée un canal d'entrée
    input_ch = channel.of('sample1', 'sample2', 'sample3')

    // Appelle le processus avec le canal d'entrée
    PROCESS_FILES(input_ch)
}

Exécuter le pipeline

Maintenant, exécutez à nouveau le workflow pour confirmer qu'il fonctionne :

nextflow run bad_syntax.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `bad_syntax.nf` [insane_faggin] DSL2 - revision: 961938ee2b

executor >  local (3)
[48/cd7f54] PROCESS_FILES (1) | 3 of 3 ✔

1.2. Utilisation de mots-clés ou directives de processus incorrects

Une autre erreur de syntaxe courante est une définition de processus invalide. Cela peut se produire si vous oubliez de définir des blocs requis ou si vous utilisez des directives incorrectes dans la définition du processus.

Exécuter le pipeline

nextflow run invalid_process.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `invalid_process.nf` [nasty_jepsen] DSL2 - revision: da9758d614

Error invalid_process.nf:3:1: Invalid process definition -- check for missing or out-of-order section labels
│   3 | process PROCESS_FILES {
│     | ^^^^^^^^^^^^^^^^^^^^^^^
│   4 |     inputs:
│   5 |     val sample_name
│   6 |
╰   7 |     output:

ERROR ~ Script compilation failed

 -- Check '.nextflow.log' file for details

Vérifier le code

L'erreur indique une "Définition de processus invalide" et montre le contexte autour du problème. En regardant les lignes 3-7, nous pouvons voir inputs: à la ligne 4, qui est le problème. Examinons invalid_process.nf :

#!/usr/bin/env nextflow

process PROCESS_FILES {
    inputs:  // ERREUR : Devrait être 'input' et non 'inputs'
    val sample_name

    output:
    path "${sample_name}_output.txt"

    script:
    """
    echo "Processing ${sample_name}" > ${sample_name}_output.txt
    """
}

workflow {

    // Crée un canal d'entrée
    input_ch = channel.of('sample1', 'sample2', 'sample3')

    // Appelle le processus avec le canal d'entrée
    PROCESS_FILES(input_ch)
}

En regardant la ligne 4 dans le contexte de l'erreur, nous pouvons repérer le problème : nous utilisons inputs au lieu de la directive correcte input. L'extension VSCode Nextflow signalera également ceci :

Corriger le code

Remplacez le mot-clé incorrect par le bon en consultant la documentation :

AprèsAvant

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:  // Corrigé : Changé 'inputs' en 'input'
    val sample_name

    output:
    path "${sample_name}_output.txt"

    script:
    """
    echo "Processing ${sample_name}" > ${sample_name}_output.txt
    """
}

workflow {

    // Crée un canal d'entrée
    input_ch = channel.of('sample1', 'sample2', 'sample3')

    // Appelle le processus avec le canal d'entrée
    PROCESS_FILES(input_ch)
}

#!/usr/bin/env nextflow

process PROCESS_FILES {
    inputs:  // ERREUR : Devrait être 'input' et non 'inputs'
    val sample_name

    output:
    path "${sample_name}_output.txt"

    script:
    """
    echo "Processing ${sample_name}" > ${sample_name}_output.txt
    """
}

workflow {

    // Crée un canal d'entrée
    input_ch = channel.of('sample1', 'sample2', 'sample3')

    // Appelle le processus avec le canal d'entrée
    PROCESS_FILES(input_ch)
}

Exécuter le pipeline

Maintenant, exécutez à nouveau le workflow pour confirmer qu'il fonctionne :

nextflow run invalid_process.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `invalid_process.nf` [silly_fermi] DSL2 - revision: 961938ee2b

executor >  local (3)
[b7/76cd9d] PROCESS_FILES (2) | 3 of 3 ✔

1.3. Utilisation de mauvais noms de variables

Les noms de variables que vous utilisez dans vos blocs de script doivent être valides, dérivés soit des entrées, soit du code groovy inséré avant le script. Mais lorsque vous gérez la complexité au début du développement de pipeline, il est facile de faire des erreurs dans la dénomination des variables, et Nextflow vous le fera savoir rapidement.

Exécuter le pipeline

nextflow run no_such_var.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `no_such_var.nf` [gloomy_meninsky] DSL2 - revision: 0c4d3bc28c

Error no_such_var.nf:17:39: `undefined_var` is not defined
│  17 |     echo "Using undefined variable: ${undefined_var}" >> ${output_pref
╰     |                                       ^^^^^^^^^^^^^

ERROR ~ Script compilation failed

 -- Check '.nextflow.log' file for details

L'erreur est détectée au moment de la compilation et pointe directement vers la variable non définie à la ligne 17, avec un caret indiquant exactement où se trouve le problème.

Vérifier le code

Examinons no_such_var.nf :

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
    val sample_name

    output:
    path "${sample_name}_processed.txt"

    script:
    // Définit les variables dans le code Groovy avant le script
    def output_prefix = "${sample_name}_processed"
    def timestamp = new Date().format("yyyy-MM-dd")

    """
    echo "Processing ${sample_name} on ${timestamp}" > ${output_prefix}.txt
    echo "Using undefined variable: ${undefined_var}" >> ${output_prefix}.txt  // ERREUR : undefined_var non définie
    """
}

workflow {
    input_ch = channel.of('sample1', 'sample2', 'sample3')
    PROCESS_FILES(input_ch)
}

Le message d'erreur indique que la variable n'est pas reconnue dans le template de script, et vous devriez pouvoir voir ${undefined_var} utilisé dans le bloc script, mais non défini ailleurs.

Corriger le code

Si vous obtenez une erreur 'No such variable', vous pouvez la corriger soit en définissant la variable (en corrigeant les noms de variables d'entrée ou en modifiant le code groovy avant le script), soit en la supprimant du bloc script si elle n'est pas nécessaire :

AprèsAvant

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
    val sample_name

    output:
    path "${sample_name}_output.txt"

    script:
    // Définit les variables dans le code Groovy avant le script
    def output_prefix = "${sample_name}_processed"
    def timestamp = new Date().format("yyyy-MM-dd")

    """
    echo "Processing ${sample_name} on ${timestamp}" > ${output_prefix}.txt
    """  // Supprime la ligne avec undefined_var
}

workflow {
    input_ch = channel.of('sample1', 'sample2', 'sample3')
    PROCESS_FILES(input_ch)
}

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
    val sample_name

    output:
    path "${sample_name}_output.txt"

    script:
    // Définit les variables dans le code Groovy avant le script
    def output_prefix = "${sample_name}_processed"
    def timestamp = new Date().format("yyyy-MM-dd")

    """
    echo "Processing ${sample_name} on ${timestamp}" > ${output_prefix}.txt
    echo "Using undefined variable: ${undefined_var}" >> ${output_prefix}.txt  // ERREUR : undefined_var non définie
    """
}

workflow {
    input_ch = channel.of('sample1', 'sample2', 'sample3')
    PROCESS_FILES(input_ch)
}

Exécuter le pipeline

Maintenant, exécutez à nouveau le workflow pour confirmer qu'il fonctionne :

nextflow run no_such_var.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `no_such_var.nf` [suspicious_venter] DSL2 - revision: 6ba490f7c5

executor >  local (3)
[21/237300] PROCESS_FILES (2) | 3 of 3 ✔

1.4. Mauvaise utilisation des variables Bash

En débutant avec Nextflow, il peut être difficile de comprendre la différence entre les variables Nextflow (Groovy) et Bash. Cela peut générer une autre forme d'erreur de variable incorrecte qui apparaît lors de la tentative d'utilisation de variables dans le contenu Bash du bloc script.

Exécuter le pipeline

nextflow run bad_bash_var.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `bad_bash_var.nf` [infallible_mandelbrot] DSL2 - revision: 0853c11080

Error bad_bash_var.nf:13:42: `prefix` is not defined
│  13 |     echo "Processing ${sample_name}" > ${prefix}.txt
╰     |                                          ^^^^^^

ERROR ~ Script compilation failed

 -- Check '.nextflow.log' file for details

Vérifier le code

L'erreur pointe vers la ligne 13 où ${prefix} est utilisé. Examinons bad_bash_var.nf pour voir ce qui cause le problème :

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
    val sample_name

    output:
    path "${sample_name}_output.txt"

    script:
    """
    prefix="${sample_name}_output"
    echo "Processing ${sample_name}" > ${prefix}.txt  # ERROR: ${prefix} is Groovy syntax, not Bash
    """
}

Dans cet exemple, nous définissons la variable prefix en Bash, mais dans un processus Nextflow, la syntaxe $ que nous avons utilisée pour y faire référence (${prefix}) est interprétée comme une variable Groovy, pas Bash. La variable n'existe pas dans le contexte Groovy, donc nous obtenons une erreur 'no such variable'.

Corriger le code

Si vous voulez utiliser une variable Bash, vous devez échapper le signe dollar comme ceci :

AprèsAvant

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
    val sample_name

    output:
    path "${sample_name}_output.txt"

    script:
    """
    prefix="${sample_name}_output"
    echo "Processing ${sample_name}" > \${prefix}.txt  # Fixed: Escaped the dollar sign
    """
}

workflow {
    input_ch = channel.of('sample1', 'sample2', 'sample3')
    PROCESS_FILES(input_ch)
}

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
    val sample_name

    output:
    path "${sample_name}_output.txt"

    script:
    """
    prefix="${sample_name}_output"
    echo "Processing ${sample_name}" > ${prefix}.txt  # ERROR: ${prefix} is Groovy syntax, not Bash
    """
}

Cela indique à Nextflow d'interpréter ceci comme une variable Bash.

Exécuter le pipeline

Maintenant, exécutez à nouveau le workflow pour confirmer qu'il fonctionne :

nextflow run bad_bash_var.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `bad_bash_var.nf` [naughty_franklin] DSL2 - revision: 58c1c83709

executor >  local (3)
[4e/560285] PROCESS_FILES (2) | 3 of 3 ✔

Variables Groovy vs Variables Bash

Pour les manipulations de variables simples comme la concaténation de chaînes ou les opérations de préfixe/suffixe, il est généralement plus lisible d'utiliser des variables Groovy dans la section script plutôt que des variables Bash dans le bloc script :

script:
def output_prefix = "${sample_name}_processed"
def output_file = "${output_prefix}.txt"
"""
echo "Processing ${sample_name}" > ${output_file}
"""

Cette approche évite le besoin d'échapper les signes dollar et rend le code plus facile à lire et à maintenir.

1.5. Instructions en Dehors du Bloc Workflow

L'extension VSCode Nextflow met en évidence les problèmes de structure de code qui causeront des erreurs. Un exemple courant est la définition de canaux en dehors du bloc workflow {} - ceci est maintenant imposé comme une erreur de syntaxe.

Exécuter le pipeline

nextflow run badpractice_syntax.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `badpractice_syntax.nf` [intergalactic_colden] DSL2 - revision: 5e4b291bde

Error badpractice_syntax.nf:3:1: Statements cannot be mixed with script declarations -- move statements into a process or workflow
│   3 | input_ch = channel.of('sample1', 'sample2', 'sample3')
╰     | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ERROR ~ Script compilation failed

 -- Check '.nextflow.log' file for details

Le message d'erreur indique clairement le problème : les instructions (comme les définitions de canaux) ne peuvent pas être mélangées avec les déclarations de script en dehors d'un bloc workflow ou process.

Vérifier le code

Examinons badpractice_syntax.nf pour voir ce qui cause l'erreur :

#!/usr/bin/env nextflow

input_ch = channel.of('sample1', 'sample2', 'sample3')  // ERREUR : Canal défini en dehors du workflow

process PROCESS_FILES {
    input:
    val sample_name

    output:
    path "${sample_name}_processed.txt"

    script:
    // Définit les variables dans le code Groovy avant le script
    def output_prefix = "${sample_name}_processed"
    def timestamp = new Date().format("yyyy-MM-dd")

    """
    echo "Processing ${sample_name} on ${timestamp}" > ${output_prefix}.txt
    """
}

workflow {
    PROCESS_FILES(input_ch)
}

L'extension VSCode soulignera également la variable input_ch comme étant définie en dehors du bloc workflow :

Corriger le code

Déplacez la définition du canal à l'intérieur du bloc workflow :

AprèsAvant

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
    val sample_name

    output:
    path "${sample_name}_processed.txt"

    script:
    // Définit les variables dans le code Groovy avant le script
    def output_prefix = "${sample_name}_processed"
    def timestamp = new Date().format("yyyy-MM-dd")

    """
    echo "Processing ${sample_name} on ${timestamp}" > ${output_prefix}.txt
    """
}

workflow {
    input_ch = channel.of('sample1', 'sample2', 'sample3')  // Déplacé à l'intérieur du bloc workflow
    PROCESS_FILES(input_ch)
}

#!/usr/bin/env nextflow

input_ch = channel.of('sample1', 'sample2', 'sample3')  // ERREUR : Canal défini en dehors du workflow

process PROCESS_FILES {
    input:
    val sample_name

    output:
    path "${sample_name}_processed.txt"

    script:
    // Définit les variables dans le code Groovy avant le script
    def output_prefix = "${sample_name}_processed"
    def timestamp = new Date().format("yyyy-MM-dd")

    """
    echo "Processing ${sample_name} on ${timestamp}" > ${output_prefix}.txt
    """
}

workflow {
    PROCESS_FILES(input_ch)
}

Exécuter le pipeline

Exécutez à nouveau le workflow pour confirmer que la correction fonctionne :

nextflow run badpractice_syntax.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `badpractice_syntax.nf` [naughty_ochoa] DSL2 - revision: 5e4b291bde

executor >  local (3)
[6a/84a608] PROCESS_FILES (2) | 3 of 3 ✔

Gardez vos canaux d'entrée définis dans le bloc workflow, et en général suivez toutes les autres recommandations faites par l'extension.

À retenir

Vous pouvez identifier et corriger systématiquement les erreurs de syntaxe en utilisant les messages d'erreur de Nextflow et les indicateurs visuels de l'IDE. Les erreurs de syntaxe courantes incluent les accolades manquantes, les mots-clés de processus incorrects, les variables non définies et l'utilisation inappropriée des variables Bash vs Nextflow. L'extension VSCode aide à détecter bon nombre de ces erreurs avant l'exécution. Avec ces compétences de débogage de syntaxe dans votre boîte à outils, vous serez capable de résoudre rapidement les erreurs de syntaxe Nextflow les plus courantes et de passer à la résolution de problèmes d'exécution plus complexes.

Et ensuite ?

Apprenez à déboguer des erreurs de structure de canal plus complexes qui se produisent même lorsque la syntaxe est correcte.

---

2. Erreurs de Structure des Canaux

Les erreurs de structure des canaux sont plus subtiles que les erreurs de syntaxe car le code est syntaxiquement correct, mais les formes de données ne correspondent pas à ce que les processus attendent. Nextflow tentera d'exécuter le pipeline, mais pourrait constater que le nombre d'entrées ne correspond pas à ce qu'il attend et échouer. Ces erreurs n'apparaissent généralement qu'à l'exécution et nécessitent une compréhension des données circulant dans votre workflow.

Débogage des Canaux avec .view()

Tout au long de cette section, rappelez-vous que vous pouvez utiliser l'opérateur .view() pour inspecter le contenu des canaux à n'importe quel point de votre workflow. C'est l'un des outils de débogage les plus puissants pour comprendre les problèmes de structure des canaux. Nous explorerons cette technique en détail dans la section 2.4, mais n'hésitez pas à l'utiliser pendant que vous travaillez sur les exemples.

my_channel.view()  // Affiche ce qui circule dans le canal

2.1. Mauvais Nombre de Canaux d'Entrée

Cette erreur se produit lorsque vous passez un nombre différent de canaux que ce qu'un processus attend.

Exécuter le pipeline

nextflow run bad_number_inputs.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `bad_number_inputs.nf` [happy_swartz] DSL2 - revision: d83e58dcd3

Error bad_number_inputs.nf:23:5: Incorrect number of call arguments, expected 1 but received 2
│  23 |     PROCESS_FILES(samples_ch, files_ch)
╰     |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ERROR ~ Script compilation failed

 -- Check '.nextflow.log' file for details

Vérifier le code

Le message d'erreur indique clairement que l'appel attendait 1 argument mais en a reçu 2, et pointe vers la ligne 23. Examinons bad_number_inputs.nf :

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
        val sample_name  // Le processus n'attend qu'une seule entrée

    output:
        path "${sample_name}_output.txt"

    script:
    """
    echo "Processing ${sample_name}" > ${sample_name}_output.txt
    """
}

workflow {

    // Crée deux canaux séparés
    samples_ch = channel.of('sample1', 'sample2', 'sample3')
    files_ch = channel.of('file1.txt', 'file2.txt', 'file3.txt')

    // ERREUR : Passe 2 canaux mais le processus n'en attend qu'un seul
    PROCESS_FILES(samples_ch, files_ch)
}

Vous devriez voir l'appel PROCESS_FILES mal apparié, fournissant plusieurs canaux d'entrée alors que le processus n'en définit qu'un. L'extension VSCode soulignera également l'appel du processus en rouge, et fournira un message de diagnostic au survol :

Corriger le code

Pour cet exemple spécifique, le processus attend un seul canal et ne nécessite pas le second canal, nous pouvons donc le corriger en passant uniquement le canal samples_ch :

AprèsAvant

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
        val sample_name  // Le processus n'attend qu'une seule entrée

    output:
        path "${sample_name}_output.txt"

    script:
    """
    echo "Processing ${sample_name}" > ${sample_name}_output.txt
    """
}

workflow {

    // Crée deux canaux séparés
    samples_ch = channel.of('sample1', 'sample2', 'sample3')
    files_ch = channel.of('file1.txt', 'file2.txt', 'file3.txt')

    // Corrigé : Passe uniquement le canal que le processus attend
    PROCESS_FILES(samples_ch)
}

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
        val sample_name  // Le processus n'attend qu'une seule entrée

    output:
        path "${sample_name}_output.txt"

    script:
    """
    echo "Processing ${sample_name}" > ${sample_name}_output.txt
    """
}

workflow {

    // Crée deux canaux séparés
    samples_ch = channel.of('sample1', 'sample2', 'sample3')
    files_ch = channel.of('file1.txt', 'file2.txt', 'file3.txt')

    // ERREUR : Passe 2 canaux mais le processus n'en attend qu'un seul
    PROCESS_FILES(samples_ch, files_ch)
}

Exécuter le pipeline

nextflow run bad_number_inputs.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `bad_number_inputs.nf` [big_euler] DSL2 - revision: e302bd87be

executor >  local (3)
[48/497f7b] PROCESS_FILES (3) | 3 of 3 ✔

Plus couramment que dans cet exemple, vous pourriez ajouter des entrées supplémentaires à un processus et oublier de mettre à jour l'appel du workflow en conséquence, ce qui peut conduire à ce type d'erreur. Heureusement, c'est l'une des erreurs les plus faciles à comprendre et à corriger, car le message d'erreur est assez clair sur le décalage.

2.2. Épuisement des Canaux (Le Processus S'Exécute Moins de Fois Que Prévu)

Certaines erreurs de structure de canal sont beaucoup plus subtiles et ne produisent aucune erreur du tout. Probablement la plus courante de celles-ci reflète un défi auquel les nouveaux·elles utilisateur·trices de Nextflow sont confronté·es en comprenant que les canaux de file peuvent être épuisés et manquer d'éléments, ce qui signifie que le workflow se termine prématurément.

Exécuter le pipeline

nextflow run exhausted.nf

Sortie de la commande

Exhausted channel output

 N E X T F L O W   ~  version 25.10.2

Launching `exhausted.nf` [extravagant_gauss] DSL2 - revision: 08cff7ba2a

executor >  local (1)
[bd/f61fff] PROCESS_FILES (1) [100%] 1 of 1 ✔

Ce workflow se termine sans erreur, mais il ne traite qu'un seul échantillon !

Vérifier le code

Examinons exhausted.nf pour voir si c'est correct :

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
    val reference
    val sample_name

    output:
    path "${output_prefix}.txt"

    script:
    // Définit les variables dans le code Groovy avant le script
    output_prefix = "${reference}_${sample_name}"
    def timestamp = new Date().format("yyyy-MM-dd")

    """
    echo "Processing ${sample_name} on ${timestamp}" > ${output_prefix}.txt
    """
}

workflow {

    reference_ch = channel.of('baseline_reference')
    input_ch = channel.of('sample1', 'sample2', 'sample3')

    PROCESS_FILES(reference_ch, input_ch)
}

Le processus ne s'exécute qu'une seule fois au lieu de trois fois car le canal reference_ch est un canal de file qui s'épuise après la première exécution du processus. Lorsqu'un canal est épuisé, l'ensemble du processus s'arrête, même si d'autres canaux ont encore des éléments.

C'est un modèle courant où vous avez un seul fichier de référence qui doit être réutilisé sur plusieurs échantillons. La solution consiste à convertir le canal de référence en canal de valeur qui peut être réutilisé indéfiniment.

Corriger le code

Il existe plusieurs façons de résoudre ce problème selon le nombre de fichiers affectés.

Option 1 : Vous avez un seul fichier de référence que vous réutilisez beaucoup. Vous pouvez simplement créer un type de canal de valeur, qui peut être utilisé encore et encore. Il y a trois façons de faire cela :

1a Utilisez channel.value() :

workflow {
    reference_ch = channel.value('baseline_reference')  // Le canal de valeur peut être réutilisé
    input_ch = channel.of('sample1', 'sample2', 'sample3')

    PROCESS_FILES(reference_ch, input_ch)
}

1b Utilisez l'opérateur first() :

workflow {
    reference_ch = channel.of('baseline_reference').first()  // Convertit en canal de valeur
    input_ch = channel.of('sample1', 'sample2', 'sample3')

    PROCESS_FILES(reference_ch, input_ch)
}

1c. Utilisez l'opérateur collect() :

workflow {
    reference_ch = channel.of('baseline_reference').collect()  // Convertit en canal de valeur
    input_ch = channel.of('sample1', 'sample2', 'sample3')

    PROCESS_FILES(reference_ch, input_ch)
}

Option 2 : Dans des scénarios plus complexes, peut-être où vous avez plusieurs fichiers de référence pour tous les échantillons dans le canal d'échantillons, vous pouvez utiliser l'opérateur combine pour créer un nouveau canal qui combine les deux canaux en tuples :

workflow {
    reference_ch = channel.of('baseline_reference','other_reference')
    input_ch = channel.of('sample1', 'sample2', 'sample3')
    combined_ch = reference_ch.combine(input_ch)  // Crée un produit cartésien

    PROCESS_FILES(combined_ch)
}

L'opérateur .combine() génère un produit cartésien des deux canaux, donc chaque élément dans reference_ch sera apparié avec chaque élément dans input_ch. Cela permet au processus de s'exécuter pour chaque échantillon tout en utilisant la référence.

Cela nécessite d'ajuster l'entrée du processus. Dans notre exemple, le début de la définition du processus devrait être ajusté comme suit :

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
        tuple val(reference), val(sample_name)

Cette approche peut ne pas convenir dans toutes les situations.

Exécuter le pipeline

Essayez l'une des corrections ci-dessus et exécutez à nouveau le workflow :

nextflow run exhausted.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `exhausted.nf` [maniac_leavitt] DSL2 - revision: f372a56a7d

executor >  local (3)
[80/0779e9] PROCESS_FILES (3) | 3 of 3 ✔

Vous devriez maintenant voir tous les trois échantillons être traités au lieu d'un seul.

2.3. Mauvaise Structure du Contenu des Canaux

Lorsque les workflows atteignent un certain niveau de complexité, il peut être un peu difficile de suivre les structures internes de chaque canal, et les gens génèrent couramment des décalages entre ce que le processus attend et ce que le canal contient réellement. C'est plus subtil que le problème dont nous avons discuté plus tôt, où le nombre de canaux était incorrect. Dans ce cas, vous pouvez avoir le bon nombre de canaux d'entrée, mais la structure interne d'un ou plusieurs de ces canaux ne correspond pas à ce que le processus attend.

Exécuter le pipeline

nextflow run bad_channel_shape.nf

Sortie de la commande

Launching `bad_channel_shape.nf` [hopeful_pare] DSL2 - revision: ffd66071a1

executor >  local (3)
executor >  local (3)
[3f/c2dcb3] PROCESS_FILES (3) [  0%] 0 of 3 ✘
ERROR ~ Error executing process > 'PROCESS_FILES (1)'

Caused by:
  Missing output file(s) `[sample1, file1.txt]_output.txt` expected by process `PROCESS_FILES (1)`


Command executed:

  echo "Processing [sample1, file1.txt]" > [sample1, file1.txt]_output.txt

Command exit status:
  0

Command output:
  (empty)

Work dir:
  /workspaces/training/side-quests/debugging/work/d6/1fb69d1d93300bbc9d42f1875b981e

Tip: when you have fixed the problem you can continue the execution adding the option `-resume` to the run command line

-- Check '.nextflow.log' file for details

Vérifier le code

Les crochets dans le message d'erreur fournissent l'indice ici - le processus traite le tuple comme une valeur unique, ce qui n'est pas ce que nous voulons. Examinons bad_channel_shape.nf :

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
        val sample_name  // Attend une valeur unique, reçoit un tuple

    output:
        path "${sample_name}_output.txt"

    script:
    """
    echo "Processing ${sample_name}" > ${sample_name}_output.txt
    """
}

workflow {

    // Le canal émet des tuples, mais le processus attend des valeurs uniques
    input_ch = channel.of(
      ['sample1', 'file1.txt'],
      ['sample2', 'file2.txt'],
      ['sample3', 'file3.txt']
    )
    PROCESS_FILES(input_ch)
}

Vous pouvez voir que nous générons un canal composé de tuples : ['sample1', 'file1.txt'], mais le processus attend une valeur unique, val sample_name. La commande exécutée montre que le processus essaie de créer un fichier nommé [sample3, file3.txt]_output.txt, ce qui n'est pas la sortie prévue.

Corriger le code

Pour corriger cela, si le processus nécessite les deux entrées, nous pourrions ajuster le processus pour accepter un tuple :

Option 1: Accepter un tuple dans le processusOption 2: Extraire le premier élément

AprèsAvant

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
        tuple val(sample_name), val(file_name)  // Corrigé : Accepte le tuple

    output:
        path "${sample_name}_output.txt"

    script:
    """
    echo "Processing ${sample_name}" > ${sample_name}_output.txt
    """
}

workflow {

    // Le canal émet des tuples, mais le processus attend des valeurs uniques
    input_ch = channel.of(
      ['sample1', 'file1.txt'],
      ['sample2', 'file2.txt'],
      ['sample3', 'file3.txt']
    )
    PROCESS_FILES(input_ch)
}

#!/usr/bin/env nextflow

process PROCESS_FILES {
    input:
        val sample_name  // Attend une valeur unique, reçoit un tuple

    output:
        path "${sample_name}_output.txt"

    script:
    """
    echo "Processing ${sample_name}" > ${sample_name}_output.txt
    """
}

workflow {

    // Le canal émet des tuples, mais le processus attend des valeurs uniques
    input_ch = channel.of(
      ['sample1', 'file1.txt'],
      ['sample2', 'file2.txt'],
      ['sample3', 'file3.txt']
    )
    PROCESS_FILES(input_ch)
}

AprèsAvant

workflow {

    // Le canal émet des tuples, mais le processus attend des valeurs uniques
    input_ch = channel.of(
      ['sample1', 'file1.txt'],
      ['sample2', 'file2.txt'],
      ['sample3', 'file3.txt']
    )
    PROCESS_FILES(input_ch.map { it[0] })  // Corrigé : Extrait le premier élément
}

workflow {

    // Le canal émet des tuples, mais le processus attend des valeurs uniques
    input_ch = channel.of(
      ['sample1', 'file1.txt'],
      ['sample2', 'file2.txt'],
      ['sample3', 'file3.txt']
    )
    PROCESS_FILES(input_ch)
}

Exécuter le pipeline

Choisissez l'une des solutions et réexécutez le workflow :

nextflow run bad_channel_shape.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `bad_channel_shape.nf` [clever_thompson] DSL2 - revision: 8cbcae3746

executor >  local (3)
[bb/80a958] PROCESS_FILES (2) | 3 of 3 ✔

2.4. Techniques de Débogage des Canaux

Utilisation de .view() pour l'Inspection des Canaux

L'outil de débogage le plus puissant pour les canaux est l'opérateur .view(). Avec .view(), vous pouvez comprendre la forme de vos canaux à toutes les étapes pour aider au débogage.

Exécuter le pipeline

Exécutez bad_channel_shape_viewed.nf pour voir cela en action :

nextflow run bad_channel_shape_viewed.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `bad_channel_shape_viewed.nf` [maniac_poisson] DSL2 - revision: b4f24dc9da

executor >  local (3)
[c0/db76b3] PROCESS_FILES (3) [100%] 3 of 3 ✔
Channel content: [sample1, file1.txt]
Channel content: [sample2, file2.txt]
Channel content: [sample3, file3.txt]
After mapping: sample1
After mapping: sample2
After mapping: sample3

Vérifier le code

Examinons bad_channel_shape_viewed.nf pour voir comment .view() est utilisé :

workflow {

    // Le canal émet des tuples, mais le processus attend des valeurs uniques
    input_ch = channel.of(
      ['sample1', 'file1.txt'],
      ['sample2', 'file2.txt'],
      ['sample3', 'file3.txt']
    )
    .view { "Channel content: $it" }  // Débogage : Affiche le contenu original du canal
    .map { tuple -> tuple[0] }        // Transformation : Extrait le premier élément
    .view { "After mapping: $it" }    // Débogage : Affiche le contenu transformé du canal

    PROCESS_FILES(input_ch)
}

Corriger le code

Pour vous éviter d'utiliser excessivement les opérations .view() à l'avenir pour comprendre le contenu des canaux, il est conseillé d'ajouter quelques commentaires pour aider :

workflow {

    // Le canal émet des tuples, mais le processus attend des valeurs uniques
    input_ch = channel.of(
            ['sample1', 'file1.txt'],
            ['sample2', 'file2.txt'],
            ['sample3', 'file3.txt'],
        ) // [sample_name, file_name]
        .map { tuple -> tuple[0] } // sample_name

    PROCESS_FILES(input_ch)
}

Cela deviendra plus important à mesure que vos workflows gagneront en complexité et que la structure des canaux deviendra plus opaque.

Exécuter le pipeline

nextflow run bad_channel_shape_viewed.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `bad_channel_shape_viewed.nf` [marvelous_koch] DSL2 - revision: 03e79cdbad

executor >  local (3)
[ff/d67cec] PROCESS_FILES (2) | 3 of 3 ✔
Channel content: [sample1, file1.txt]
Channel content: [sample2, file2.txt]
Channel content: [sample3, file3.txt]
After mapping: sample1
After mapping: sample2
After mapping: sample3

À retenir

De nombreuses erreurs de structure de canal peuvent être créées avec une syntaxe Nextflow valide. Vous pouvez déboguer les erreurs de structure de canal en comprenant le flux de données, en utilisant des opérateurs .view() pour l'inspection, et en reconnaissant les modèles d'erreur comme les crochets indiquant des structures de tuple inattendues.

Et ensuite ?

Apprenez les erreurs créées par les définitions de processus.

---

3. Erreurs de Structure des Processus

La plupart des erreurs que vous rencontrerez liées aux processus seront liées à des erreurs que vous avez faites dans la formation de la commande, ou à des problèmes liés au logiciel sous-jacent. Cela dit, de manière similaire aux problèmes de canal ci-dessus, vous pouvez faire des erreurs dans la définition du processus qui ne sont pas des erreurs de syntaxe, mais qui causeront des erreurs à l'exécution.

3.1. Fichiers de Sortie Manquants

Une erreur courante lors de l'écriture de processus est de faire quelque chose qui génère un décalage entre ce que le processus attend et ce qui est généré.

Exécuter le pipeline

nextflow run missing_output.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `missing_output.nf` [zen_stone] DSL2 - revision: 37ff61f926

executor >  local (3)
executor >  local (3)
[fd/2642e9] process > PROCESS_FILES (2) [ 66%] 2 of 3, failed: 2
ERROR ~ Error executing process > 'PROCESS_FILES (3)'

Caused by:
  Missing output file(s) `sample3.txt` expected by process `PROCESS_FILES (3)`


Command executed:

  echo "Processing sample3" > sample3_output.txt

Command exit status:
  0

Command output:
  (empty)

Work dir:
  /workspaces/training/side-quests/debugging/work/02/9604d49fb8200a74d737c72a6c98ed

Tip: when you have fixed the problem you can continue the execution adding the option `-resume` to the run command line

-- Check '.nextflow.log' file for details

Vérifier le code

Le message d'erreur indique que le processus s'attendait à produire un fichier de sortie nommé sample3.txt, mais le script crée en réalité sample3_output.txt. Examinons la définition du processus dans missing_output.nf :

process PROCESS_FILES {
    input:
    val sample_name

    output:
    path "${sample_name}.txt"  // Attend : sample3.txt

    script:
    """
    echo "Processing ${sample_name}" > ${sample_name}_output.txt  // Crée : sample3_output.txt
    """
}

Vous devriez voir qu'il y a un décalage entre le nom du fichier de sortie dans le bloc output:, et celui utilisé dans le script. Ce décalage cause l'échec du processus. Si vous rencontrez ce type d'erreur, retournez vérifier que les sorties correspondent entre votre définition de processus et votre bloc de sortie.

Si le problème n'est toujours pas clair, vérifiez le répertoire de travail lui-même pour identifier les fichiers de sortie réels créés :

❯ ls -h work/02/9604d49fb8200a74d737c72a6c98ed
sample3_output.txt

Pour cet exemple, cela nous mettrait en évidence qu'un suffixe _output est incorporé dans le nom du fichier de sortie, contrairement à notre définition output:.

Corriger le code

Corrigez le décalage en rendant le nom de fichier de sortie cohérent :

AprèsAvant

process PROCESS_FILES {
    input:
    val sample_name

    output:
    path "${sample_name}_output.txt"  // Corrigé : Correspond à la sortie du script

    script:
    """
    echo "Processing ${sample_name}" > ${sample_name}_output.txt
    """
}

process PROCESS_FILES {
    input:
    val sample_name

    output:
    path "${sample_name}.txt"  // Attend : sample3.txt

    script:
    """
    echo "Processing ${sample_name}" > ${sample_name}_output.txt  // Crée : sample3_output.txt
    """
}

Exécuter le pipeline

nextflow run missing_output.nf

Sortie de la commande

N E X T F L O W   ~  version 25.10.2

Launching `missing_output.nf` [elated_hamilton] DSL2 - revision: 961938ee2b

executor >  local (3)
[16/1c437c] PROCESS_FILES (3) | 3 of 3 ✔

3.2. Logiciel manquant

Une autre classe d'erreurs se produit en raison d'erreurs dans la fourniture de logiciels. missing_software.nf est un workflow syntaxiquement valide, mais il dépend d'un logiciel externe pour fournir la commande cowpy qu'il utilise.

Exécuter le pipeline

nextflow run missing_software.nf

Sortie de la commande

ERROR ~ Error executing process > 'PROCESS_FILES (3)'

Caused by:
  Process `PROCESS_FILES (3)` terminated with an error exit status (127)


Command executed:

  cowpy sample3 > sample3_output.txt

Command exit status:
  127

Command output:
  (empty)

Command error:
  .command.sh: line 2: cowpy: command not found

Work dir:
  /workspaces/training/side-quests/debugging/work/82/42a5bfb60c9c6ee63ebdbc2d51aa6e

Tip: you can try to figure out what's wrong by changing to the process work directory and showing the script file named `.command.sh`

-- Check '.nextflow.log' file for details

Le processus n'a pas accès à la commande que nous spécifions. Parfois, c'est parce qu'un script est présent dans le répertoire bin du workflow, mais n'a pas été rendu exécutable. D'autres fois, c'est parce que le logiciel n'est pas installé dans le conteneur ou l'environnement où le workflow s'exécute.

Vérifier le code

Attention à ce code de sortie 127 - il vous dit exactement le problème. Examinons missing_software.nf :

process PROCESS_FILES {

    container 'community.wave.seqera.io/library/cowpy:1.1.5--3db457ae1977a273'

    input