Troubleshooting Taxonomic Profiling: Common Errors and Solutions When Using Kraken2 and MetaPhlAn

By Dr. Zubair Khalid, DVM, MS, PhD · 2026-08-20

Key Takeaways

• Database integrity and version control are paramount: Errors such as "Out of memory" or "Killed" during Kraken2 database loading often stem from insufficient RAM, necessitating smaller databases, increased memory allocation, or memory-mapped mode. Incompatibility errors, indicated by unexpected taxonomy IDs or classification failures, arise from mismatches between Kraken2/MetaPhlAn software versions and their corresponding databases, requiring database rebuilding or redownloading with checksum verification.
• Classification sensitivity is directly linked to read length and database content: Low classification rates, characterized by a high unclassified read fraction, can result from short reads that lack sufficient k-mers for Kraken2 or insufficient marker gene coverage for MetaPhlAn. Solutions include host DNA removal to eliminate non-microbial reads and considering database choice or parameter adjustments for short-read data.
• Reproducibility hinges on meticulous record-keeping: A comprehensive version manifest detailing profiler software, database versions and download dates, reference genome sets, and classification parameters is critical. This, alongside an analysis log capturing commands, resource usage, and troubleshooting steps, prevents data drift and facilitates error diagnosis.
• Discordant results between Kraken2 and MetaPhlAn are informative, not necessarily erroneous: Discrepancies often reflect their distinct classification strategies (k-mer matching vs. marker genes) and differing reference databases. Investigating these differences at the genus level, examining read support, and considering biological plausibility are key to determining whether the discordance signals a database gap, a parameter mismatch, or a genuine biological signal.
• Post-classification filtering and quality control are essential for biological relevance: Raw output requires filtering based on minimum read counts, relative abundance, or confidence scores to remove low-confidence classifications and potential artifacts. The use of positive (e.g., mock communities) and negative (e.g., blank extractions) controls is vital for validating filtering effectiveness and identifying contamination.

Taxonomic profiling of shotgun metagenomic data with Kraken2 or MetaPhlAn frequently fails at specific, identifiable points: database construction and memory allocation, read length and classification sensitivity mismatches, reference database version drift, and post-classification filtering decisions. This article provides a systematic troubleshooting framework for researchers who have installed these tools, run them on real data, and encountered errors or biologically implausible results. The guidance assumes basic command-line proficiency and focuses on concrete diagnostic steps, record-keeping practices, and escalation criteria for problems that require deeper intervention.

Scope and Reader Context

This troubleshooting guide addresses the distinct failure modes that arise when running Kraken2 and MetaPhlAn on shotgun metagenomic sequencing data. The content is written for biology students, researchers, laboratory professionals, and life-science practitioners who have moved beyond tutorial examples and are now processing real samples. The problems covered include memory exhaustion during database loading, database incompatibility errors, unexpectedly low classification rates, discordant results between the two tools, and downstream analysis artifacts that originate from upstream profiling choices.

The guidance does not cover every possible error message. Instead, it organizes troubleshooting around the most common categories of failure observed in practice: environment and installation problems, database construction and selection errors, classification parameter mismatches, and interpretation errors that arise after classification is complete. Each section provides diagnostic steps, practical solutions, and criteria for when to escalate the problem to a more specialized resource.

At a Glance

The table below summarizes the most common failure categories, their typical symptoms, primary causes, and first-line solutions. Use this table as a rapid triage tool before reading the detailed sections.

Core Principles of Taxonomic Profiling Troubleshooting

Classification Is a Reference-Dependent Process

Both Kraken2 and MetaPhlAn assign taxonomy by comparing sequencing reads against reference databases, but they use fundamentally different strategies. Kraken2 classifies individual reads by examining k-mers against a database of complete genomes, while MetaPhlAn uses clade-specific marker genes to estimate the relative abundance of organisms present in a sample. Understanding this distinction is essential for troubleshooting because the same sample can produce different results from the two tools without either tool being broken.

The reference database is the single most important determinant of classification outcomes. NCBI maintains the primary sequence databases that most taxonomic profilers draw upon, and the content of these databases changes continuously as new genomes are deposited and existing annotations are corrected [<a href="#ref-1">1</a>]. When your classification results change between runs of the same data, the first question to ask is whether the database changed, not whether your analysis code changed.

Reproducibility Requires Version Documentation

Taxonomic profiling results are not reproducible unless you record the exact versions of every component in your workflow. This includes the profiler software version, the database build version, the database download date, the reference genome set used to build the database, and the parameters used for classification. The Galaxy Training Network emphasizes that reproducible analysis depends on documenting the tools and parameters used at each step, because small changes in any component can alter results [<a href="#ref-2">2</a>]. Similarly, nf-core pipeline documentation stresses that community workflows must specify exact software versions and configuration parameters to ensure that results can be compared across runs and institutions [<a href="#ref-3">3</a>].

The practical implication is that your troubleshooting records should include a version manifest for every analysis. When an error appears, the version manifest is the first document to consult. When results change unexpectedly, the version manifest reveals which component changed.

Errors Are Often Configuration Problems, Not Software Bugs

Many errors in taxonomic profiling arise from misconfiguration instead of defects in the software itself. Research on configuration errors in software systems shows that misconfiguration is a major cause of software failure, and diagnosing these errors is challenging because of the complex relationship between configuration options and the operating environment [<a href="#ref-4">4</a>]. Taxonomic profiling tools have many configuration options, including database paths, memory settings, thread counts, and classification thresholds. A small error in any of these settings can produce a confusing failure.

The troubleshooting approach recommended here follows the pattern used in other technical domains: identify the error message, check the configuration options that relate to that error, and test changes systematically. Automated approaches to configuration troubleshooting exist, but for most researchers, a disciplined manual approach with good records is sufficient [<a href="#ref-4">4</a>].

Practical Workflow for Diagnosing Profiler Failures

Step 1: Capture the Exact Error Message and Context

When a taxonomic profiling run fails, the first action is to capture the complete error message, the command that produced it, the software version, and the database version. Do not rely on memory. Save the error output to a file, record the command history, and note the date and time. This information is the foundation of all subsequent troubleshooting.

Common error messages and their immediate implications include:

• "Out of memory" or "Killed" indicates that the process exceeded available RAM. This is a resource allocation problem, not a software defect.
• "Database file not found" or "Cannot open database" indicates a path error or incomplete database download.
• "Taxonomy ID not found" or "Invalid taxid" indicates a mismatch between the database and the taxonomy files.
• "Segmentation fault" or "Bus error" often indicates corrupted database files or incompatible software versions.

Step 2: Verify the Environment

Before investigating the profiler itself, confirm that the computing environment is sound. Check available disk space, memory, and CPU resources. Verify that the software was installed correctly and that all dependencies are present. The Bioconductor project provides extensive documentation on package installation and environment configuration for genomic analysis, and similar principles apply to command-line tools [<a href="#ref-5">5</a>]. If you are working in a shared computing environment, confirm that the module or container you are using matches the documentation for the version you intend to run.

Step 3: Isolate the Variable

When a run fails, change one variable at a time. If you suspect the database, test with a different database. If you suspect the input data, test with a small subset of reads. If you suspect the parameters, test with default parameters. Changing multiple variables simultaneously makes it impossible to identify the cause of the failure.

Step 4: Test with a Minimal Example

Create a small test dataset from your actual data, such as 10,000 reads from a single sample, and run the profiler with default parameters. If the minimal example succeeds, the problem is likely related to data volume, sample complexity, or parameter choices. If the minimal example fails, the problem is likely in the software installation, database, or environment.

Step 5: Document the Outcome

Record the outcome of each troubleshooting step, including what was changed, what was observed, and what conclusion was drawn. This record serves two purposes: it prevents repeating failed experiments, and it provides the information needed if you escalate the problem to a colleague, a support forum, or a specialized training resource.

Database Construction and Selection

Standard Databases and Their Limitations

Kraken2 and MetaPhlAn ship with standard databases that are convenient for initial use but may be inadequate for specific research questions. The standard Kraken2 database includes a defined set of reference genomes, while MetaPhlAn's default database includes a specific set of marker genes. Both databases are updated periodically, and the version you download determines the taxonomy reference space for your analysis.

The NCBI databases that underlie these reference sets are continuously updated as new sequences are submitted and existing records are revised [<a href="#ref-1">1</a>]. This means that a database downloaded six months ago may produce different results than a database downloaded today, even when analyzing the same sequencing data. For research projects that will be compared across time or across institutions, recording the database version and download date is essential.

Building Custom Databases

When the standard database does not meet your needs, you may need to build a custom database. This is common when working with understudied organisms, specific environments, or novel pathogens. The process involves downloading reference genomes, formatting them for the profiler, and building the database index. This process is computationally intensive and requires careful attention to the format expected by the profiler.

A protocol for analyzing fungal profiles from fecal metagenomes illustrates the challenges of working with organisms that are poorly represented in standard databases. The authors note that identifying fungal profiles from metagenomes is challenging due to an incomplete fungal database and limitations in the understanding of the software [<a href="#ref-6">6</a>]. Their protocol describes steps for raw data retrieval, elimination of human genome and contaminants, and assigning taxonomy labels to fungal reads, highlighting that custom workflows are often necessary for specific research questions [<a href="#ref-6">6</a>].

Database Version Mismatches

A common error occurs when the profiler software and the database are built with incompatible versions. This can produce errors during database loading, unexpected taxonomy IDs in the output, or silent misclassification. The solution is to ensure that the database and the software are compatible, which typically means downloading both from the same release or building the database with the same software version that will be used for classification.

The EMBL-EBI training resources provide guidance on using biological databases effectively, including understanding database versions and updates [<a href="#ref-7">7</a>]. Researchers who understand how databases are versioned and updated are better equipped to diagnose version-related errors.

Memory and Resource Management

Understanding Kraken2 Memory Requirements

Kraken2 databases are loaded into memory for classification, and the memory requirement depends on the size of the database. The standard Kraken2 database requires a substantial amount of RAM, and larger custom databases require correspondingly more memory. When the database exceeds available RAM, the process is killed, often with an "out of memory" error or a "Killed" message from the operating system.

The solution options are:

• Use a smaller database, such as the standard database instead of a custom database with many genomes.
• Increase the memory allocation for the job, which may require requesting a different compute node or adjusting job submission parameters.
• Use Kraken2's memory-mapped mode, which allows the database to be read from disk instead of loaded entirely into RAM, at the cost of slower classification.

Managing Concurrent Jobs

In shared computing environments, multiple users running large databases simultaneously can exhaust available memory. If your job fails with an out-of-memory error, check whether other jobs are consuming memory on the same node. Coordinating resource usage with other users or scheduling jobs during off-peak hours can resolve this issue.

Recording Resource Usage

For each analysis, record the peak memory usage, the database size, and the number of threads used. This information helps predict resource requirements for future analyses and provides context when troubleshooting memory-related failures. The nf-core documentation emphasizes that workflow configuration must account for the resources required by each step, and that resource specifications should be recorded as part of the workflow configuration [<a href="#ref-3">3</a>].

Read Length and Classification Sensitivity

The Relationship Between Read Length and Classification

Kraken2 classifies reads by matching k-mers to the database, and the sensitivity of classification depends on the read length and the k-mer size used to build the database. Short reads, such as those produced by some sequencing platforms, may not contain enough informative k-mers for confident classification. This can result in a high fraction of unclassified reads or classification at a higher taxonomic level than expected.

MetaPhlAn uses a different approach, mapping reads to clade-specific marker genes. The sensitivity of MetaPhlAn depends on the completeness of the marker gene database and the sequencing depth of the sample. Low-abundance organisms may not be detected if the sequencing depth is insufficient to cover their marker genes.

Diagnosing Low Classification Rates

When the classification rate is lower than expected, the first diagnostic step is to examine the read length distribution of your data. If the reads are shorter than the minimum length required by the profiler, classification will fail. The second step is to check for host contamination. Reads from the host organism, such as human DNA in clinical samples, will not be classified by a database that does not include the host genome. Removing host reads before classification can substantially increase the classification rate.

The protocol for analyzing fungal profiles from fecal metagenomes explicitly includes a step for eliminating human genome and contaminants before assigning taxonomy labels [<a href="#ref-6">6</a>]. This step is not optional for samples that may contain host DNA. The protocol authors describe this as a necessary part of the workflow, not an optional quality control measure [<a href="#ref-6">6</a>].

Adjusting Parameters for Read Length

Both Kraken2 and MetaPhlAn have parameters that affect sensitivity to short reads. Adjusting these parameters can improve classification rates for short-read data, but the adjustments must be made with an understanding of the tradeoff between sensitivity and specificity. Increasing sensitivity may increase false positive classifications, while decreasing sensitivity may miss true positives.

The Galaxy Training Network provides tutorials on metagenomic analysis that include guidance on parameter selection for different data types [<a href="#ref-2">2</a>]. These tutorials are a useful reference when adjusting parameters for your specific data.

Host Contamination and Preprocessing

Why Host Removal Matters

Metagenomic samples, particularly those from clinical or environmental sources, often contain a substantial fraction of host DNA. This host DNA competes with microbial DNA for sequencing reads, reducing the effective sequencing depth for microbial organisms. More importantly for taxonomic profiling, host reads that are not removed before classification can be misclassified as microbial, producing false positive results.

The protocol for analyzing fungal profiles from fecal metagenomes includes human genome and contaminant elimination as a distinct step in the workflow [<a href="#ref-6">6</a>]. This step is described as essential for obtaining accurate taxonomic profiles, particularly for low-abundance organisms that may be masked by host contamination [<a href="#ref-6">6</a>].

Implementing Host Removal

Host removal is typically performed by mapping reads to the host reference genome and removing the mapped reads. The remaining reads are considered to be of microbial origin and are used for taxonomic profiling. The choice of host reference genome and the mapping parameters affect the stringency of host removal.

For human samples, the human reference genome is used. For other host organisms, the appropriate reference genome must be obtained from NCBI [<a href="#ref-1">1</a>]. The NCBI database provides reference genomes for a wide range of organisms, and the quality of the reference genome affects the effectiveness of host removal [<a href="#ref-1">1</a>].

Verifying Host Removal Effectiveness

After host removal, verify that the fraction of host reads is reduced to an acceptable level. This can be done by mapping the remaining reads to the host genome and checking the mapping rate. If a substantial fraction of reads still map to the host genome, the host removal step was not effective, and the parameters should be adjusted.

Post-Classification Filtering and Quality Control

The Need for Filtering

Raw classification output from Kraken2 and MetaPhlAn contains many low-confidence classifications that should be filtered before downstream analysis. These include classifications based on a small number of reads, classifications at very low abundance, and classifications that are likely to be artifacts of sequencing errors or database errors.

The vvv2_display tool, developed for viral genome analysis, illustrates the importance of filtering low-frequency or non-significant variants from analysis output [<a href="#ref-8">8</a>]. The authors note that variants often yield numerous low-frequency or non-significant variants, yet only a small fraction are biologically relevant [<a href="#ref-8">8</a>]. The same principle applies to taxonomic profiling: the raw output contains many classifications that are not biologically meaningful, and filtering is required to identify the relevant signal.

Establishing Filtering Thresholds

Filtering thresholds should be established based on the research question and the characteristics of the data. Common thresholds include a minimum number of reads per taxon, a minimum relative abundance, and a minimum confidence score. The thresholds should be recorded and applied consistently across all samples in a study.

The choice of thresholds affects the results, and different thresholds can produce different conclusions. For this reason, the thresholds should be justified in the methods section of any publication and should be applied consistently across all samples.

Using Controls to Assess Filtering

Positive and negative controls are essential for assessing the effectiveness of filtering. A positive control, such as a mock community with known composition, can be used to assess the accuracy of the profiling pipeline. A negative control, such as a blank extraction control, can be used to identify contaminants that should be filtered from the results.

The Galaxy Training Network provides guidance on using controls in metagenomic analysis workflows [<a href="#ref-2">2</a>]. The use of controls is a standard practice in metagenomics and is essential for interpreting the results of taxonomic profiling.

Discordant Results Between Kraken2 and MetaPhlAn

Why the Tools Disagree

Kraken2 and MetaPhlAn use different reference databases and different classification strategies, so it is expected that they will produce somewhat different results. Kraken2 classifies individual reads against a database of complete genomes, while MetaPhlAn uses clade-specific marker genes. These different approaches have different strengths and weaknesses, and the results can diverge for specific taxa.

The divergence is most pronounced for taxa that are poorly represented in one database but well represented in the other. For example, a taxon with many complete genomes in the NCBI database but few marker genes in the MetaPhlAn database will be detected by Kraken2 but may be missed by MetaPhlAn.

Investigating Discordant Results

When the two tools produce discordant results, the first step is to determine whether the discordance is at the species level or the genus level. Species-level discordance is common and often reflects the different resolution of the two tools. Genus-level discordance is more concerning and warrants investigation.

The investigation should include:

• Checking the read counts supporting each classification
• Examining the specific reads that were classified differently
• Verifying that the databases are current and appropriate for the sample type
• Considering whether the discordance reflects a real biological difference or a technical artifact

Reporting Discordant Results

When discordant results are reported, the methods section should describe both tools, the database versions, and the parameters used. The results section should present the findings from both tools and discuss the discrepancies. This transparency allows readers to assess the robustness of the conclusions.

The EMBL-EBI training resources emphasize the importance of understanding the strengths and limitations of different bioinformatics tools [<a href="#ref-7">7</a>]. Researchers who understand the tools they use are better equipped to interpret discordant results and to communicate the limitations of their analysis.

Common Failure Patterns and Their Resolutions

Pattern 1: The Process Is Killed During Database Loading

Symptoms: The job terminates immediately or shortly after starting, often with an "out of memory" or "Killed" message.

Diagnosis: The database requires more memory than is available to the process.

Resolution: Check the available memory on the compute node, reduce the database size, increase the memory allocation, or use memory-mapped mode.

Prevention: Record the memory requirements of the database and the available memory on the compute node before submitting the job.

Pattern 2: Classification Fails With a Database Error

Symptoms: The profiler reports that the database cannot be opened, is corrupted, or is incompatible with the software version.

Diagnosis: The database file is missing, corrupted, or built with an incompatible software version.

Resolution: Redownload the database, verify the checksum, and confirm that the database and software versions are compatible.

Prevention: Document the database version and software version for every analysis, and verify compatibility before starting a large job.

Pattern 3: The Classification Rate Is Very Low

Symptoms: A large fraction of reads are unclassified, or the classification is dominated by a few taxa that are not expected in the sample.

Diagnosis: The reads are too short for the database settings, the database lacks relevant taxa, or host contamination is present.

Resolution: Check the read length distribution, remove host reads, and consider whether the database is appropriate for the sample type.

Prevention: Perform quality control on the input data, remove host reads, and verify that the database includes the taxa expected in the sample.

Pattern 4: Results Change Between Runs of the Same Data

Symptoms: Re-running the same analysis produces different results.

Diagnosis: The database version changed, the software version changed, or the parameters changed.

Resolution: Check the version manifest and the command history to identify what changed.

Prevention: Record all versions and parameters, and use a workflow management system to ensure consistency.

Pattern 5: The Results Are Biologically Implausible

Symptoms: The taxonomic profile includes taxa that are impossible or highly unlikely in the sample type, or the relative abundances are extreme.

Diagnosis: Contamination, database errors, or filtering thresholds that are too permissive.

Resolution: Check for contamination using negative controls, verify the database, and apply more stringent filtering.

Prevention: Use positive and negative controls, apply consistent filtering thresholds, and verify results against known biology.

Records and Measurements

The Version Manifest

For every taxonomic profiling analysis, maintain a version manifest that records:

• The profiler software version
• The database version and download date
• The reference genome set used to build the database
• The parameters used for classification
• The input data file names and checksums
• The date and time of the analysis
• The computing environment, including operating system and resource allocation

This manifest is the primary tool for diagnosing unexpected results and for ensuring reproducibility.

The Analysis Log

In addition to the version manifest, maintain an analysis log that records:

• The commands used for each step
• The output of each command, including error messages
• The resource usage, including peak memory and runtime
• Any deviations from the planned workflow
• The outcome of each step, including any troubleshooting performed

The analysis log provides the context needed to diagnose errors and to communicate the analysis to collaborators or reviewers.

The Troubleshooting Record

When a problem occurs, maintain a troubleshooting record that documents:

• The error message and the context in which it occurred
• The diagnostic steps performed
• The results of each diagnostic step
• The resolution applied
• The outcome of the resolution

This record prevents repeating failed experiments and provides the information needed for escalation.

Limitations and Interpretation Boundaries

What Taxonomic Profiling Can and Cannot Tell You

Taxonomic profiling identifies which organisms are present in a sample and estimates their relative abundance. It does not provide information about the functional potential of the organisms, their viability, or their activity. These limitations should be considered when interpreting the results.

The protocol for analyzing fungal profiles from fecal metagenomes notes that identifying fungal profiles is challenging due to an incomplete fungal database and limitations in the understanding of the software [<a href="#ref-6">6</a>]. This statement applies broadly to taxonomic profiling: the results are limited by the completeness of the reference database and the accuracy of the software.

The Reference Database Is a Limitation

The reference database is the most significant limitation of taxonomic profiling. Organisms that are not represented in the database cannot be classified, and organisms that are closely related to database entries may be misclassified. The NCBI databases are continuously updated, but they are not complete [<a href="#ref-1">1</a>]. Researchers should be aware of the limitations of the database they use and should consider whether the database is appropriate for their research question.

The Interpretation Boundary

Taxonomic profiling results should be interpreted within the context of the research question and the limitations of the methods. A taxonomic profile is a hypothesis about the composition of the microbial community, not a definitive measurement. The results should be validated with complementary methods when possible, and the limitations should be acknowledged in publications.

The Galaxy Training Network provides training on metagenomic analysis that emphasizes the importance of understanding the limitations of the methods [<a href="#ref-2">2</a>]. Researchers who understand the limitations are better equipped to interpret their results and to communicate the uncertainty to others.

Safety and Regulatory Context

Data Handling and Privacy

Metagenomic data from clinical samples may contain human DNA and other sensitive information. Researchers must comply with applicable regulations regarding the handling and storage of human data. Host removal is also a technical step but also a privacy measure, as it reduces the amount of human sequence data in the analysis.

The NCBI provides resources for understanding the regulatory and ethical considerations of working with sequence data [<a href="#ref-1">1</a>]. Researchers should consult these resources and their institutional review boards before beginning metagenomic analysis of clinical samples.

Computational Resource Stewardship

In shared computing environments, researchers have a responsibility to use computational resources efficiently. This includes requesting appropriate resources for the job, not running unnecessary large jobs, and coordinating with other users. The nf-core documentation emphasizes that workflow configuration should be appropriate for the available resources [<a href="#ref-3">3</a>].

Reproducibility as a Professional Standard

Reproducibility is a professional standard in bioinformatics research. The Carpentries lessons provide foundational training in reproducible research practices, including version control, documentation, and automation [<a href="#ref-9">9</a>]. Researchers who follow these practices are better equipped to troubleshoot errors and to communicate their methods to others.

Professional Escalation Criteria

When to Seek Help

Some problems cannot be resolved with the troubleshooting steps described in this article. Escalate the problem when:

• The error persists after trying the recommended solutions
• The error message indicates a problem with the software itself, not the configuration
• The results are consistently implausible across multiple samples and databases
• The problem requires expertise beyond your current level of training

Where to Seek Help

The following resources are appropriate for escalation:

• The software documentation and issue tracker for the specific tool
• The Galaxy Training Network, which provides tutorials and a community of users [<a href="#ref-2">2</a>]
• The nf-core community, which provides workflow standards and support [<a href="#ref-3">3</a>]
• The Bioconductor community, which provides support for genomic analysis packages [<a href="#ref-5">5</a>]
• The EMBL-EBI training resources, which provide structured learning pathways [<a href="#ref-7">7</a>]

What to Include When Seeking Help

When seeking help, provide:

• The exact error message
• The version manifest
• The command that produced the error
• A minimal example that reproduces the error
• The troubleshooting steps already attempted
• The relevant input data characteristics

Providing this information allows others to diagnose the problem efficiently and reduces the time to resolution.

A Structured Decision Framework for Profiler Output Discrepancies

When Kraken2 and MetaPhlAn produce conflicting taxonomic profiles from the same input data, researchers often treat the disagreement as an error to be eliminated. A more productive approach is to treat the discrepancy as information that can be resolved through a structured decision framework. This section provides a practical method for classifying the type of discordance, determining whether it reflects a technical artifact or a genuine biological signal, and deciding which result to trust for downstream analysis.

Classifying the Type of Discordance

The first step in the decision framework is to categorize the discrepancy by taxonomic level and by the direction of the disagreement. Record the discordance in a structured format that captures the taxon name, the rank at which the disagreement occurs, the classification status in each tool, and the supporting read counts or abundance estimates from each tool. This record becomes the basis for all subsequent decisions.

Discordance falls into three practical categories. The first category is detection discordance, where one tool reports a taxon as present and the other does not report it at all. The second category is abundance discordance, where both tools detect the taxon but report substantially different relative abundances. The third category is resolution discordance, where both tools detect the organism but assign it to different taxonomic levels, such as one tool reporting a species and the other reporting only the genus.

Each category has different implications and requires different investigative steps. Detection discordance often indicates a reference database gap in one tool. Abundance discordance frequently reflects the different mathematical approaches used by the two tools. Resolution discordance typically arises from the different classification strategies, where Kraken2 assigns individual reads and MetaPhlAn relies on clade-specific marker genes.

Applying the Decision Matrix

Once the discordance is categorized, apply the decision matrix below to determine the appropriate response. The matrix considers the taxonomic level of the disagreement, the read support in each tool, and the biological plausibility of each result.

The decision matrix directs you to the most likely cause and the first action to take. It does not replace investigation but provides a structured starting point that prevents random parameter changes.

Investigating the Underlying Cause

After classifying the discordance and consulting the decision matrix, investigate the specific cause using targeted checks. For detection discordance, verify that the taxon is present in the reference database of the tool that failed to detect it. The NCBI databases that underlie taxonomic profilers are continuously updated, and a taxon that was absent from an older database may be present in a newer version [<a href="#ref-1">1</a>]. Check the database build date and compare it to the date the taxon was added to the reference sequence collection.

For abundance discordance, examine the marker gene content for the taxon in MetaPhlAn and the genome representation in Kraken2. A taxon with few marker genes in the MetaPhlAn database will have less reliable abundance estimates, while a taxon with many closely related genomes in the Kraken2 database may have inflated read assignments. The protocol for analyzing fungal profiles from fecal metagenomes notes that incomplete databases and limitations in software understanding create challenges for accurate profiling [<a href="#ref-6">6</a>]. This observation applies directly to abundance discordance, where the completeness of the reference data determines the reliability of the estimate.

For resolution discordance, examine the actual reads that were classified differently by the two tools. Extract the reads assigned to the taxon by each tool and align them to the relevant reference sequences. This direct examination often reveals whether the reads support the finer or the coarser assignment. The vvv2_display tool for viral variant analysis demonstrates the value of cross-referenced outputs that link visual summaries to detailed tabular data [<a href="#ref-8">8</a>]. A similar approach, where you link the classification output to the underlying read alignments, provides the evidence needed to resolve resolution discordance.

Deciding Which Result to Use

The decision framework concludes with a practical determination of which result to carry forward into downstream analysis. The decision depends on the research question and the nature of the discordance.

For detection discordance where one tool reports a taxon and the other does not, the conservative approach is to treat the taxon as present only if the detecting tool provides strong read support and the taxon is biologically plausible for the sample type. If the taxon is biologically implausible and appears only in one tool, treat it as a probable false positive and investigate the database content for potential contamination or misannotation.

For abundance discordance, the decision depends on whether the research question requires absolute or relative comparisons. If the question is about the presence or absence of taxa, abundance discordance is less critical. If the question involves comparing relative abundances across samples, the choice of tool matters. In this case, apply the same tool consistently across all samples and document the choice in the methods. The EMBL-EBI training resources emphasize that understanding the strengths and limitations of different bioinformatics tools is essential for interpreting their outputs [<a href="#ref-7">7</a>].

For resolution discordance, the decision depends on the taxonomic resolution required by the research question. If species-level resolution is essential, investigate whether the finer assignment is supported by the read evidence. If the reads support only genus-level assignment, report the genus and note the limitation. The Galaxy Training Network provides tutorials on metagenomic analysis that include guidance on interpreting taxonomic assignments at different resolution levels [<a href="#ref-2">2</a>].

Recording the Decision and Its Rationale

Every decision made through this framework should be recorded in the analysis log. The record should include the discordance category, the taxon involved, the evidence examined, the decision made, and the rationale for the decision. This record serves multiple purposes. It provides transparency for publications and collaborations. It allows the decision to be revisited if new information becomes available. It prevents the same discordance from being investigated repeatedly in future analyses.

The nf-core documentation emphasizes that reproducible workflows require documentation of also the commands and parameters but also the decisions made during the analysis [<a href="#ref-3">3</a>]. Recording the decision and its rationale is an essential component of reproducibility for taxonomic profiling studies.

Escalation Criteria for Persistent Discordance

Some discordance cannot be resolved through the decision framework and requires escalation. Escalate the problem when the discordance persists across multiple samples, when the discordance involves taxa that are central to the research question, or when the investigation reveals potential database errors that affect many taxa.

When escalating, provide the complete discordance record, including the taxon names, the classification outputs from both tools, the read support evidence, and the database versions. This information allows a specialist to diagnose the problem efficiently. The Carpentries lessons provide foundational training in organizing and documenting analysis work, which is directly applicable to preparing escalation materials [<a href="#ref-9">9</a>].

The decision framework described in this section transforms discordant results from an obstacle into a diagnostic opportunity. By classifying the discordance, investigating the underlying cause, and recording the decision, researchers can resolve discrepancies systematically and produce more reliable taxonomic profiles.

Frequently Asked Questions

Why does Kraken2 run out of memory even though I have a large amount of RAM?

Kraken2 loads the entire database into memory for classification, and the memory requirement depends on the database size. The standard database requires a substantial amount of RAM, and custom databases with many genomes require correspondingly more. Check the available memory on the compute node, reduce the database size, or use memory-mapped mode to read the database from disk instead of loading it entirely into RAM.

What does the "database file not found" error mean?

This error indicates that Kraken2 or MetaPhlAn cannot locate the database file at the path specified. Check that the database was downloaded or built correctly, that the path is correct, and that the file permissions allow reading. If the database was downloaded, verify the checksum to ensure the file is not corrupted.

Why is my classification rate so low?

A low classification rate can result from short read lengths, host contamination, or a database that lacks the taxa present in your sample. Check the read length distribution of your data, remove host reads before classification, and verify that the database includes the taxa expected in your sample type.

Why do Kraken2 and MetaPhlAn give different results for the same data?

Kraken2 and MetaPhlAn use different reference databases and different classification strategies. Kraken2 classifies individual reads against complete genomes, while MetaPhlAn uses clade-specific marker genes. These different approaches have different strengths and weaknesses, and the results can diverge for specific taxa. Compare the results at the genus level and investigate any genus-level discordance.

How do I know if my database is appropriate for my sample type?

The database should include the taxa expected in your sample type. For example, a database built primarily from human-associated genomes may not be appropriate for environmental samples. Check the database documentation to understand its content, and consider whether the taxa you expect are represented.

What should I do if my results are biologically implausible?

First, check for contamination using negative controls. Second, verify that the database is appropriate for your sample type. Third, apply more stringent filtering thresholds. If the results remain implausible, escalate the problem to a more specialized resource.

How do I make my taxonomic profiling analysis reproducible?

Record the software version, database version, database download date, parameters, and input data checksums for every analysis. Use a workflow management system to ensure consistency, and document any deviations from the planned workflow. The nf-core documentation provides guidance on reproducible workflow standards [<a href="#ref-3">3</a>].

When should I build a custom database instead of using the standard database?

Build a custom database when the standard database lacks the taxa relevant to your research question. This is common when working with understudied organisms, specific environments, or novel pathogens. The protocol for analyzing fungal profiles from fecal metagenomes illustrates the need for custom workflows when the standard database is incomplete [<a href="#ref-6">6</a>].

Related Bioinformatics Guides

• Metagenomics Taxonomic Classification: Kraken2 and Functional Annotation Pipelines
• Genomic Data Analysis Tools: A Comparative Guide for Researchers
• How to Interpret Gene Set Enrichment Analysis Results
• Metagenomics Pipeline: From Raw Reads to Taxonomic and Functional Profiles
• Metagenomics Functional Profiling: Tools and Databases for Pathway Analysis

Related Clinical & Scientific Guides

• A Practical Guide to Detecting Antimicrobial Resistance Genes in Shotgun Metagenomic Data
• Computational Immunology: Modeling the Immune System
• How to Set Hard Filters for Germline Variant Calling: A Practical Guide to GATK Best Practices

References and Further Reading

This article is educational and does not replace validated analysis plans, institutional policy, clinical interpretation, or specialist review.