nf-llm-debugger: An Open-Source Plugin for Automatically Diagnosing Nextflow Pipeline Errors Using LLM

nf-llm-debugger is a Nextflow plugin that can automatically intercept pipeline errors at runtime, analyze logs using local or remote large language models (LLMs), and output clear, actionable repair suggestions.

• Original Author/Maintainer: Luca Cozzuto (biocorecrg)
• Source Platform: GitHub
• Original Title: nf-llm-debugger
• Original Link: https://github.com/biocorecrg/nf-llm-debugger
• Open Source License: MIT License

In the fields of bioinformatics and high-performance computing, Nextflow has become the framework of choice for building reproducible and scalable data analysis pipelines. However, as pipeline complexity increases, debugging becomes increasingly challenging. A typical Nextflow pipeline may contain dozens of processes, involving multiple software containers, resource allocation strategies, and data dependencies. When a process fails, developers often have to deal with lengthy log files, obscure exit codes (such as 126, 127, 1, etc.), and complex error stack traces.

Traditional debugging methods usually require developers to manually consult documentation, search for error information, and analyze log contexts—this process is not only time-consuming but also requires developers to have in-depth knowledge of various tools. For newcomers to bioinformatics, this debugging barrier is particularly high.

nf-llm-debugger is an open-source Nextflow plugin developed by Luca Cozzuto, which cleverly integrates the capabilities of large language models (LLMs) into the pipeline debugging process. The core value of this plugin lies in its ability to automatically intercept errors at runtime, use AI to analyze the root causes of failures, and directly output structured diagnostic reports and repair suggestions.

The design of this plugin embodies several important engineering concepts. First is runtime integration: it is deeply embedded into the JVM lifecycle via Nextflow's TraceObserver interface, enabling real-time capture of process and workflow failure events. Second is open compatibility: the plugin uses an OpenAI-compatible API format and supports multiple LLM backends such as Llamafile, Ollama, LocalAI, and OpenAI, allowing users to choose flexibly based on privacy and performance requirements. Third is zero-configuration local operation: for scenarios where data privacy is a concern, the plugin provides out-of-the-box local LLM support, enabling offline operation without complex configuration.

The plugin implements runtime error interception via Nextflow's TraceObserver mechanism. When a process or workflow in the pipeline fails, the plugin immediately captures relevant error information, including process name, exit code, standard output, and standard error streams. This design ensures that error information is not lost and can be fully passed to the LLM for analysis.

The plugin communicates with LLMs using the standard OpenAI Chat Completions API format. This design decision brings significant flexibility advantages: users can use any local or remote service compatible with the OpenAI API. For local deployment, Llamafile and Ollama provide lightweight solutions; for scenarios requiring more powerful capabilities, commercial APIs such as OpenAI and Gemini are also supported.

After the LLM returns the analysis results, the plugin converts technical error information into a structured, easy-to-understand diagnostic report. The report not only identifies the cause of the error but also provides specific repair steps, greatly reducing the cognitive burden of debugging.