3.23.0

3.23.0

Multi-reference datasets

Datasets can now include multiple reference sequences for auto-detection by nextclade sort and Nextclade Web. This enables reliable dataset suggestion for genetically diverse pathogens (e.g. enteroviruses) where no single reference sequence is close enough to all circulating lineages.

Dataset authors list additional reference FASTA files in the new minimizerIndex field of pathogen.json. The detection fingerprint is built from the union of k-mers across all listed references. The suggestion score divides by the expected hits from a single reference, so adding references broadens the detection range without diluting scores.

Multi-reference detection is transparent: Nextclade Web suggestions, nextclade sort output format, alignment, mutation calling, and all analysis outputs are unchanged. Existing single-reference datasets are unaffected. The minimizer index is validated on load, rejecting malformed entries with clear errors. See datasets documentation, #1771.

Installation and usage 📚 Documentation: docs.nextstrain.org/projects/nextclade 🌍 Nextclade Web: clades.nextstrain.org 🖥️ Nextclade CLI: 📥 Standalone native executables can be downloaded using the links in the "Assets" section just below. Mind the different operating systems and computer architectures. 🐋 Docker images are available on DockerHub 🐍 Conda package is available in bioconda channel. ⌨️ Source code is on GitHub: github.com/nextstrain/nextclade 🚩 Report bugs, suggest features by submitting a GitHub issue 💾 Nextclade datasets are here

3.22.0

3.22.0

Nextclade Web: configurable Relative-to dropdown ordering

Dataset authors can now control the order and visibility of entries in the Nextclade Web "Relative to" dropdown via a new ref_nodes.order object in the reference tree JSON. This is a display-only setting and does not affect CLI output. See reference tree documentation, #1779.

Fix: version comparison for dataset and minimizer index selection

Schema and algorithm versions were compared as strings, causing incorrect ordering when version components exceeded single digits (e.g. 3.10.0 sorted before 3.9.0). Datasets or minimizer indexes could be rejected, mis-sorted, or silently downgraded. Version comparison now uses numeric parsing. See #1769.

Fix: web update notification version check

The update-available notification in Nextclade Web compared version strings lexicographically, which could suppress or falsely trigger the update banner when version numbers crossed single-digit boundaries. The comparison now uses semver. See #1770.

CI: GitHub Actions Node.js runtime update

GitHub Actions workflows now use the current Node.js runtime, replacing the deprecated Node 20 runtime. See #1775.

Installation and usage 📚 Documentation: docs.nextstrain.org/projects/nextclade 🌍 Nextclade Web: clades.nextstrain.org 🖥️ Nextclade CLI: 📥 Standalone native executables can be downloaded using the links in the "Assets" section just below. Mind the different operating systems and computer architectures. 🐋 Docker images are available on DockerHub 🐍 Conda package is available in bioconda channel. ⌨️ Source code is on GitHub: github.com/nextstrain/nextclade 🚩 Report bugs, suggest features by submitting a GitHub issue 💾 Nextclade datasets are here

3.21.2

3.21.2

Fix: phylogenetic placement of sequences with large internal deletions

Sequences with large internal deletions were placed near the root of the reference tree instead of near their true closest relatives. The nearest node distance metric treated node mutations at deleted positions as if the query had the reference allele, making the root appear closest because it has no mutations. Deleted positions are now treated as uninformative (like N) in the distance calculation, so they no longer bias placement toward or away from any node. See #1765.

Installation and usage 📚 Documentation: docs.nextstrain.org/projects/nextclade 🌍 Nextclade Web: clades.nextstrain.org 🖥️ Nextclade CLI: 📥 Standalone native executables can be downloaded using the links in the "Assets" section just below. Mind the different operating systems and computer architectures. 🐋 Docker images are available on DockerHub 🐍 Conda package is available in bioconda channel. ⌨️ Source code is on GitHub: github.com/nextstrain/nextclade 🚩 Report bugs, suggest features by submitting a GitHub issue 💾 Nextclade datasets are here

3.21.1

3.21.1

Fix: allow numeric keys in Auspice coloring scale

Auspice JSON v2 allows both string and numeric values as the first element of coloring scale entries. Nextclade previously only accepted strings, causing deserialization failures when loading Auspice JSONs with continuous colorings (e.g. nextstrain.org/rsv/a/genome/6y). Numeric scale keys are now accepted. See nextstrain/rsv#129, #1764 by @victorlin.

Installation and usage 📚 Documentation: docs.nextstrain.org/projects/nextclade 🌍 Nextclade Web: clades.nextstrain.org 🖥️ Nextclade CLI: 📥 Standalone native executables can be downloaded using the links in the "Assets" section just below. Mind the different operating systems and computer architectures. 🐋 Docker images are available on DockerHub 🐍 Conda package is available in bioconda channel. ⌨️ Source code is on GitHub: github.com/nextstrain/nextclade 🚩 Report bugs, suggest features by submitting a GitHub issue 💾 Nextclade datasets are here

3.21.0

3.21.0

Docker: arm64 multi-platform images

Docker images are now built for both amd64 and arm64 architectures. Pulling any Nextclade Docker image on an ARM64 host (Apple Silicon, AWS Graviton, Raspberry Pi) now gets a native image instead of requiring emulation. See #1761, #1762.

Docker: multiple base image versions

Docker images are now published for multiple base image versions: 6 Alpine releases and 3 Debian releases, covering approximately 3 and 5 years respectively. Users can pin to a specific base version using tags like :alpine3.18 or :debian11. Unversioned tags (:alpine, :debian) point to the latest base version. See the full list of available tags and platforms on Docker Hub.

Docker: breaking changes

• Default Debian base image changed from Debian 11 (Bullseye) to Debian 13 (Trixie). Users depending on Debian 11 can pin to :debian11.
• Scratch image: binary moved from /nextclade to /usr/bin/nextclade. Using nextclade without a path still works. Users referencing the absolute path /nextclade should update to /usr/bin/nextclade.

Installation and usage 📚 Documentation: docs.nextstrain.org/projects/nextclade 🌍 Nextclade Web: clades.nextstrain.org 🖥️ Nextclade CLI: 📥 Standalone native executables can be downloaded using the links in the "Assets" section just below. Mind the different operating systems and computer architectures. 🐋 Docker images are available on DockerHub 🐍 Conda package is available in bioconda channel. ⌨️ Source code is on GitHub: github.com/nextstrain/nextclade 🚩 Report bugs, suggest features by submitting a GitHub issue 💾 Nextclade datasets are here

3.20.0

3.20.0

Nextclade Web: show genome coverage outline behind "too many markers" message

When viewing dense regions with many mutations, the sequence view shows a "too many markers" message. The genome coverage outline is now visible behind this message, providing context about sequence coverage even when individual markers cannot be displayed. See #1759, #1760 for details.

Nextclade schemas: typed dataset attributes field

Dataset attributes (attributes field in pathogen.json and dataset index) have been refactored from free-form key-value pairs to typed structs with explicit fields. The new structure provides better validation and documentation for dataset metadata fields like name, reference name, reference accession, and clade. The previous free-form attributes map is no longer supported.

Nextclade schemas: cleanup

Several deprecated and unused fields have been removed from the dataset schema:

• Removed enabled field from datasets (was unused)
• Removed official field from datasets (community datasets are now detected by path prefix)
• Removed deprecated and experimental fields from VirusProperties: compatibility, shortcuts, files, defaultCds, cdsOrderPreference

These changes simplify the schema and remove legacy fields that were no longer used. Dataset authors should remove these fields from their pathogen.json files.

Nextclade schemas: documentation improvements

Added doc comments and examples to JSON schema types, improving auto-completion and inline documentation in editors that support JSON Schema. Types with new documentation include:

• Dataset index types (DatasetIndexJson, DatasetCollection, Dataset, DatasetVersion)
• Output types (NextcladeOutputs, ResultsJson, NextcladeErrorOutputs)
• QC config and result types
• Tree and Auspice extension types
• Gene and annotation types
• Mutation and alignment types
• Pathogen config and phenotype types
• Alignment parameter types

Nextclade documentation

• Fixed ref_nodes field types and added missing qry[].name field
• Added missing fields to pathogen config documentation
• Marked clade_node_attrs.displayName as required per schema
• Corrected searchAlgo enum value from ancestor-latest to ancestor-nearest
• Documented aaMutLabelMap (previously a TODO placeholder)
• Fixed QC examples to use cdsName instead of geneName

Installation and usage 📚 Documentation: docs.nextstrain.org/projects/nextclade 🌍 Nextclade Web: clades.nextstrain.org 🖥️ Nextclade CLI: 📥 Standalone native executables can be downloaded using the links in the "Assets" section just below. Mind the different operating systems and computer architectures. 🐋 Docker images are available on DockerHub 🐍 Conda package is available in bioconda channel. ⌨️ Source code is on GitHub: github.com/nextstrain/nextclade 🚩 Report bugs, suggest features by submitting a GitHub issue 💾 Nextclade datasets are here

3.19.0

3.19.0

Update Auspice tree visualization to 2.67.0

Auspice tree visualization package has been updated from 2.59.1 to 2.67.0. See Auspice changelog here.

Nextclade Web: fix tree page stuck at loading screen

The tree visualization page could get stuck showing a loading spinner indefinitely after analysis completed. This has been fixed. See #1721 for details.

Nextclade Web: fix duplicate sequence warnings

The results table could show false "duplicate sequence" warnings during and after analysis due to duplicate-name tracking data being appended repeatedly on each incremental result update. Additionally, stale tracking data from a previous analysis run was not cleared when starting a new run. See #1734, #1744 for details.

Nextclade Web: fix auto-scroll hiding dataset search results

In the dataset selector, typing a search term caused the list to auto-scroll to the previously highlighted dataset, pushing filtered search results out of view. Auto-scroll now only triggers when the user explicitly selects a different dataset and no search term is active. See #1746, #1747 for details.

Nextclade Web: handle undefined dataset gracefully

When a stale or invalid dataset was stored in the browser's local storage, navigating to the results, tree, or export pages could crash with an "Internal Error: Dataset not found" message. These pages now show a recovery UI with a link to return to the start page. The tree navigation link is also disabled until analysis has run. See #1745, #1748 for details.

Nextclade Web: show actual WASM panic messages

When the Rust code running inside WebAssembly encounters an internal error (panic), Nextclade Web now displays the actual error message with file location instead of the generic "null pointer passed to rust" message. The "copy error" button formats the error in a code block for direct pasting into GitHub issues. See #1749, #1750 for details.

Nextclade Web: fix missing row index on error and pending rows

Error and pending rows in the results table were missing the row index column, causing them to appear visually misaligned with successful result rows. See #1751 for details.

Nextclade Web: document Chrome Private Network Access restrictions

Starting with v141, Chromium-based browsers (Chrome, Edge, Brave, Opera) block requests from HTTPS origins (like https://clades.nextstrain.org) to localhost URLs due to Local Network Access security restrictions. This affects loading local files via URL parameters (e.g., ?dataset-server=http://localhost:3001). The documentation now explains the restriction and provides workarounds. See #1753 for details.

Fix integer overflow in alignment band area calculation

Fixed an integer overflow in the alignment band area calculation that could occur on 32-bit platforms (including WebAssembly in browsers) when aligning very long or highly divergent sequences. The band area now uses 64-bit integers, and additional overflow checks have been added to band dimension calculations. See #1749 for details.

Improve error message when alignment band area is exceeded

When the alignment band area limit is exceeded, Nextclade now displays a more informative error message. Large numbers are formatted for readability (e.g., "3.7B" instead of "3704350009"), and the message differentiates between likely causes based on the query-to-reference length ratio: concatenated sequences or assembly scaffolds when the query is much longer than the reference, or structural rearrangements or wrong reference when lengths are similar. See #1752 for details.

Nextclade CLI: automatic retry for network requests

Nextclade CLI now automatically retries transient network failures when downloading datasets. This improves reliability on flaky connections. Retryable conditions include network errors, 5xx server errors, 429 rate limiting, and 408 timeouts. The retry budget is scoped per host with a maximum of 3 retries per request. See #1723 for details.

Nextclade CLI: Mozilla CA certificates fallback for minimal containers

Nextclade CLI now bundles Mozilla's root CA certificates as a fallback for environments where system certificates are not installed (e.g., minimal Docker containers like debian:stable or ubuntu:22.04 without the ca-certificates package). Previously, Nextclade CLI would fail with a "No CA certificates were loaded from the system" error in such environments. System certificates and user-provided certificates via --extra-ca-certs are still loaded when available and combined with the bundled Mozilla roots. See #726, #1723 for details.

Nextclade CLI: zstd compression for HTTP transfers

Nextclade CLI now accepts zstd content encoding for HTTP responses when downloading datasets. Zstd was already supported for file decompression; this extends it to the HTTP transfer layer, where it joins gzip, brotli, and deflate. See #1723 for details.

Major dependency upgrades

Nextclade has been upgraded to Rust 2024 edition, along with updates to the Rust and WebAssembly toolchains, Node.js, React, Next.js, and many other dependencies. See #1716, #1719 for details.

Installation and usage 📚 Documentation: docs.nextstrain.org/projects/nextclade 🌍 Nextclade Web: clades.nextstrain.org 🖥️ Nextclade CLI: 📥 Standalone native executables can be downloaded using the links in the "Assets" section just below. Mind the different operating systems and computer architectures. 🐋 Docker images are available on DockerHub 🐍 Conda package is available in bioconda channel. ⌨️ Source code is on GitHub: github.com/nextstrain/nextclade 🚩 Report bugs, suggest features by submitting a GitHub issue 💾 Nextclade datasets are here

3.18.1

3.18.1

Fix: allow --output-annotation-gff and --output-annotation-tbl as sole output arguments

Nextclade CLI now correctly allows --output-annotation-gff and --output-annotation-tbl to be used as standalone output arguments without requiring other output files like --output-tsv or --output-all. Previously, using only these annotation output arguments would incorrectly trigger an error requiring at least one other output file argument to be specified. See #1707 for details. Thanks @ammaraziz for bug report.

Installation and usage 📚 Documentation: docs.nextstrain.org/projects/nextclade 🌍 Nextclade Web: clades.nextstrain.org 🖥️ Nextclade CLI: 📥 Standalone native executables can be downloaded using the links in the "Assets" section just below. Mind the different operating systems and computer architectures. 🐋 Docker images are available on DockerHub 🐍 Conda package is available in bioconda channel. ⌨️ Source code is on GitHub: github.com/nextstrain/nextclade 🚩 Report bugs, suggest features by submitting a GitHub issue 💾 Nextclade datasets are here

3.18.0

3.18.0

Dataset version selector

Nextclade Web now includes a dataset version (tag) selector in single-dataset mode. This allows you to select a specific version of a dataset instead of always using the latest version. This is useful when you want to reproduce results using an older dataset version or when testing unreleased dataset updates.

Dataset collection badges

Dataset collection names are now displayed as colored badges in the dataset info section in Nextclade Web. These badges show which collection each dataset belongs to (e.g., "nextstrain" or "community" collections) and include optional icons for better visual distinction.

Customizable "Relative to" dropdown

Dataset authors can now customize the display names and descriptions for built-in entries in the "Relative to" dropdown (reference, parent, and clade founder nodes) in Nextclade Web. This allows datasets to provide more context-specific terminology for phylogenetic comparison targets. See #1683 for details.

Fix "Reset" button behavior

The "Reset" button in the "Select dataset" section on the main page of Nextclade Web now correctly clears the currently selected dataset(s) in both single-dataset and multi-dataset modes.

Fix dataset loading and persistence issues

Numerous fixes have been made to improve dataset loading and persistence in Nextclade Web:

• Fixed dataset persistence after page reload
• Fixed loading single datasets from localhost servers using ?dataset-url parameter
• Fixed handling of ?dataset-server URL parameter during initialization
• Fixed handling of ?dataset-tag URL parameter: non-latest tags no longer cause "dataset not found" errors
• Fixed automatic updating of datasets when using the latest tag: Nextclade now picks up new versions automatically unless you explicitly select an older version
• Improved detection of non-default dataset servers to ensure correct dataset persistence behavior

Fix "updated at" date-time formatting

Fixed "updated at" date-time formatting in Nextclade Web to display seconds consistently across all dataset tags

Improve error messages when invalid dataset tags are specified

When an invalid dataset tag is provided via ?dataset-tag URL parameter or selected in the dataset version dropdown, Nextclade Web now displays a clearer error message indicating that the specified tag was not found.

Fix dataset clearing when switching dataset servers

Dataset selection is now properly cleared when switching to a non-default dataset server

JSON schema additions

Added JSON schema definitions for Auspice Nextclade extensions (.meta.extensions.nextclade), enabling better validation and tooling support for dataset authors.

Installation and usage 📚 Documentation: docs.nextstrain.org/projects/nextclade 🌍 Nextclade Web: clades.nextstrain.org 🖥️ Nextclade CLI: 📥 Standalone native executables can be downloaded using the links in the "Assets" section just below. Mind the different operating systems and computer architectures. 🐋 Docker images are available on DockerHub 🐍 Conda package is available in bioconda channel. ⌨️ Source code is on GitHub: github.com/nextstrain/nextclade 🚩 Report bugs, suggest features by submitting a GitHub issue 💾 Nextclade datasets are here

3.17.0

3.17.0

Add trailing semicolon to Newick format output

Newick format output now includes a trailing semicolon for better compatibility with parsers.

Remove extra quotation marks around filepaths

Nextclade would erroneously add double quotation marks when printing paths. This has been fixed.

Add more JSON schema definitions

We have added JSON schema definitions for Dataset and DatasetCollection types, both are parts of the DatasetIndexJson. You can find the latest definitions and documentation here

Add $schema field to JSON outputs

We have added an optional $schema field to JSON input and output files. This is a convention used to indicate which JSON schema definition the output conforms to. This can be useful for validation and for tooling that supports JSON schema (e.g. autocomplete and documentation in VSCode when editing pathogen.json file).

Installation and usage 📚 Documentation: docs.nextstrain.org/projects/nextclade 🌍 Nextclade Web: clades.nextstrain.org 🖥️ Nextclade CLI: 📥 Standalone native executables can be downloaded using the links in the "Assets" section just below. Mind the different operating systems and computer architectures. 🐋 Docker images are available on DockerHub 🐍 Conda package is available in bioconda channel. ⌨️ Source code is on GitHub: github.com/nextstrain/nextclade 🚩 Report bugs, suggest features by submitting a GitHub issue 💾 Nextclade datasets are here