Nextflow linter errors on custom Groovy code in lib/ as not being defined

[clintval]

Bug report

Expected behavior and actual behavior

Running nextflow lint ./ on a project that has Groovy classes in lib/ and using those classes in the Nextflow script and processes should not return a "is not defined" error. Instead, an error like this appears:

Error main.nf:5:5: `MyHelpers` is not defined
│   5 |     MyHelpers.SayHi
╰     |     ^^^^^^^^^

Nextflow linting complete!
 ❌ 1 file had 1 error

Steps to reproduce the problem

Make a little Groovy helper at lib/MyHelpers.groovy:

/** Helpers for my Nextflow project. */
class MyHelpers {
    public static final String SayHi = "echo 'Hello, World!'"
}

And a Nextflow script to use that helper:

process say_something {
    output: stdout()
    script: MyHelpers.SayHi
}

workflow { say_something() | view }

Program output

Running the script works:

❯ nextflow run main.nf
...
[f4/d8349f] say_something | 1 of 1 ✔
Hello, World!

But no matter how I used the Groovy code, I can't get it to lint successfully:

❯ nextflow lint ./
Error main.nf:5:5: `MyHelpers` is not defined
│   5 |     MyHelpers.SayHi
╰     |     ^^^^^^^^^

Nextflow linting complete!
 ❌ 1 file had 1 error

I suspect the linter is not compiling and accessing code in lib/.

Environment

• Nextflow version: 25.10.2
• Java version: OpenJDK Runtime Environment Homebrew (build 23.0.2)
• Operating system: MacOS
• Bash version: zsh 5.9 (arm64-apple-darwin24.0)

[bentsherman]

Thanks for reporting. I think I never got around to implementing this for nextflow lint. The problem I see is that it's not as clear which path should be used for the lib directory.

For a basic solution we could just use the current directory, or the parent directory of the input if only one input is provided (e.g. nextflow lint .). But if I give multiple inputs (e.g. nextflow lint foo/ bar/) then it becomes more complicated. Are they two separate "projects" with their own lib directories? Or are they subfolders of a single project with the lib directory as a sibling?

So I think we need to try to resolve these questions before implementing something at the risk of having weird or inconsistent behavior

Summarizing the current state for myself:

• nextflow run supports the lib directory with or without the strict parser. The ScriptLoaderV2 passes the Session class loader to the ScriptCompiler, and this class loader includes ${projectDir}/lib in its classpath

• The language server supports the lib directory relative to the project root. It uses a custom approach for this (GroovyLibCache). I have a PR (Add lib directory to classpath language-server#98) that tries to just use the class loader like nextflow run, but it wasn't working last time I tried. If this can be solved, it might make it easier to support nextflow lint as well

• nextflow lint doesn't support the lib directory at all. In theory it should be able to just use the class loader like nextflow run. Might be nice to decouple that piece from the Session. I don't expect to have any issues here like with the language server PR.

[sstrong99]

i'm running in to this issue too. I'm wondering if there is a workaround in the meantime? Thanks!

[scwatts]

@sstrong99 not so much a workaround but I was able to use the fixed linter and check my pipeline code by compiling Nextflow with the relevant changes:

nextflow_version=v26.02.0-edge--1-lint-import-fix

(
  git clone -b cmd-lint-lib-dir https://github.com/nextflow-io/nextflow;
  cd nextflow/;
  git merge --no-edit v26.02.0-edge;
  sed -i '1s/^.*$/'${nextflow_version}'/' VERSION;
  sed -i '/^version=/ { s/=.*/='${nextflow_version}'/ }' modules/nextflow/src/main/resources/META-INF/build-info.properties;
  make pack;
)

./nextflow/build/releases/nextflow-${nextflow_version}-dist -version

[scwatts]

And thanks for directing to this issue @bentsherman, I have two questions:

• now that the strict parser generally expects fully-qualified names to reference classes, is it (or will it) be possible to do the same for classes defined in the lib/ directory? I understand the lib/ directory classes are an exception to this requirement but it would be nice to consistently use fully-qualified names throughout a pipeline
• if you're planning another edge release before 26.04, would it be possible to include the changes in the linked PR?

[bentsherman]

now that the strict parser generally expects fully-qualified names to reference classes, is it (or will it) be possible to do the same for classes defined in the lib/ directory?

It should be possible, but I have noticed that it behaves weirdly. The package names seem to be inferred from the directory structure within lib, not the actual package declarations. I don't know why it is this way

if you're planning another edge release before 26.04, would it be possible to include the changes in the linked PR?

Yes, I will try to include it in the next edge. We just released 26.03.0-edge but we plan to do a .1, .2, etc before 26.04