Make plugin metadata prefetch failure non-fatal

[jorgee]

Summary

Fixes #7013

• Make HttpPluginRepository.prefetch() catch exceptions and log a warning instead of aborting startup
• Initialize the plugins map to an empty HashMap on failure so that getPlugin() can still attempt on-demand lazy fetches later
• Refactor tests to verify prefetch error tolerance while still testing fetchMetadata() error behavior directly

Context

When all plugins are pinned to exact versions and pre-installed locally, Nextflow unconditionally calls the plugin registry API at startup. If the registry is unreachable, the run aborts even though the fetched metadata would never be used.

This affects users in airlocked/firewalled environments who pre-install plugins into container images. NXF_OFFLINE=true works around it but also blocks remote pipeline cloning, making it unusable for environments that need to fetch pipelines from a Git server.

With this fix, the prefetch error is deferred — it only surfaces later if something genuinely needs the metadata (version resolution for unpinned plugins, download URLs for missing plugins).

Test plan

• HttpPluginRepositoryTest — all 9 tests pass
• All nextflow.plugin.* tests pass
• Manual: pre-install a plugin, block registry access, verify nextflow run succeeds

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for nextflow-docs-staging canceled.

Name	Link
🔨 Latest commit	e295c8e
🔍 Latest deploy log	https://app.netlify.com/projects/nextflow-docs-staging/deploys/69d90144a874270008326101

[jorgee]

Tested without connectivity to registry.

• When no plugin available: Print warning and fail because it can't download the plugin

 N E X T F L O W   ~  version 26.03.2-edge

WARN: Failed to prefetch plugin metadata - Unable to connect to https://registry.nextflow.io/api/v1/plugins/dependencies?plugins=nf-schema%402.4.2&nextflowVersion=26.03.2-edge - cause: null
Downloading plugin nf-schema@2.4.2
ERROR ~ Plugin with id nf-schema not found in any repository

• When plugin version is pinned and exists: Print the warning message at prefetch and succesfuly run the pipeline

 N E X T F L O W   ~  version 26.03.2-edge

WARN: Failed to prefetch plugin metadata - Unable to connect to https://registry.nextflow.io/api/v1/plugins/dependencies?plugins=nf-schema%402.4.2&nextflowVersion=26.03.2-edge - cause: null
Launching `main.nf` [nostalgic_almeida] revision: 6b4f49b787

Plugin loaded successfully

• When no pinned version: Print the warning and fail because can't check latest version.

 N E X T F L O W   ~  version 26.03.2-edge

WARN: Failed to prefetch plugin metadata - Unable to connect to https://registry.nextflow.io/api/v1/plugins/dependencies?plugins=nf-schema&nextflowVersion=26.03.2-edge - cause: null
ERROR ~ Cannot find latest version of nf-schema plugin

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

[pditommaso]

Let's keep only warn

[MatthiasZepper]

Thanks for addressing this problem, it was indeed causing an issue for us at NGI (me) when setting up a recent Nextflow version on our HPC.

Already in its current form, this will likely work perfectly for us. However, since there is already an environment variable NXF_DISABLE_CHECK_LATEST, you could optionally extent its reach to not only disable checking for the latest Nextflow version, but also for the latest plugin versions?

That would introduce a 4th case: When no pinned version, but NXF_DISABLE_CHECK_LATEST=true : Print a warning and try using the most recent locally available version of the plugin.

I see why allowing this may cause hard to debug issues (incompatible Nextflow/Plugin combinations?), but also reckon that few developers and almost no users will actually track the minimally required plugin version. If somebody is already keeping their NXF_HOME around for a while and adding to it, it will likely contain several older versions of a plugin and the most recent of them may actually work. Giving the user the power to launch a "Try with what is locally available" run seems helpful in certain edge cases such as a read-only shared plugin directory on an HPC?

[pditommaso]

I wonder if NXF_OFFLINE should be honoured and therefore the call to the registry skipped at all

[bentsherman]

I wonder if NXF_OFFLINE should be honoured and therefore the call to the registry skipped at all

It is honored, but NXF_OFFLINE also causes local git repositories to not work: #6988

In fact it might be simpler to fix that issue. Then you could just run with NXF_OFFLINE=true

[bentsherman]

I'm starting to think this PR is the wrong approach. I think we could standardize on the following pattern for plugins, modules, and pipelines:

• If NXF_OFFLINE=true, use only the local cache and fail if something is not available locally
• Otherwise, use the local cache but always check remote source for latest version

This already works for plugins, we just need to fix #6988 for pipelines. I think modules also effectively work this way even though they don't explicitly check NXF_OFFLINE