.. |PipeCraft2_logo| image:: _static/PipeCraft2_icon_v2.png
  :width: 50
  :target: https://github.com/pipecraft2/pipecraft

.. |learnErrors| image:: _static/troubleshoot/learnErrors.png
  :width: 250

.. |dimnames| image:: _static/troubleshoot/dimnames.png
  :width: 250

.. |learnErrors_fewReads| image:: _static/troubleshoot/learnErrors_fewReads.png
  :width: 250

.. |workflow_stopped| image:: _static/troubleshoot/workflow_stopped.png
  :width: 250
  
.. |debug| image:: _static/debug.png
  :width: 100

.. |DADA2_read_identifiers| image:: _static/troubleshoot/DADA2_read_identifiers.png
  :width: 250

=================================
Troubleshooting |PipeCraft2_logo| 
=================================

This page is developing based on the user feedback.

____________________________________________________

Debugging mode
==============

Turn on '**debugging mode**' (bottom-right button) to keep temporary (log) files for identifying the cause of the error

|debug|

____________________________________________________


General errors
==============

.. admonition:: "rm: cannot remove ... File is not accessible"
  :class: error

  **Possible reason**: The file is being used by another process OR Docker does not have permissions to delete the file(s).

  **Fix**: Close all other applications that might be using the file / Delete the file manually when attempting to rerun the workflow.

____________________________________________________

.. admonition:: BBmap error in metaMATE (memory error)
  :class: error

  if a reference database (``reference seqs``) is very large, then the process may require a lot of RAM.
  If you receive an error message "*.ERROR: BBMap alignment produced no matches and a memory error was detected*", 
  then you may need to increase the :ref:`memory (RAM) allocated to Docker <manage_resources>` and or close other applications that are using a lot of RAM.

__________________________________________________

.. admonition:: No files in the output folder, but PipeCraft said "Workflow finished"
  :class: error

  **Possible reason**: Computer's memory (RAM) is full, and process was killed. Cannot finish the analyses with those local resources. 

  **Possible fix**: In Windows, try to increase the RAM size accessible to Docker (see :ref:`here <increase_RAM>`).
  Check if there was a README.txt output and read that. Please :ref:`report <contact>` unexpexted errors. 

____________________________________________________

.. admonition:: No OTU_table.txt with version v0.1.4
  :class: error

  **Possible reason**: known bug.

  **Fix**: Fixed the bug. Reinstall PipeCraft v0.1.4 (or higher)

____________________________________________________

.. admonition:: "ERROR]: cannot find files with specified extension"
  :class: error
  
  **Possible reason**: wrongly specified working directory or extension; OR issues with external hard drives in Windows.

  **Fix**: Double-check the specified directory and extention; OR **restart Docker engine**.

____________________________________________________

.. admonition:: Workflow stopped
  :class: error

  |workflow_stopped|

  **Possible reason**: Computer's memory (RAM) is full, and process was killed. Cannot finish the analyses with those local resources. 

  **Possible fix**: In Windows, try to increase the RAM size accessible to Docker (see :ref:`here <increase_RAM>`).

____________________________________________________

.. admonition:: Error in DADA2 quality filtering (filterAndTrim)
  :class: error

  |DADA2_read_identifiers|

  **Possible reason**: wrong read identifiers for ``read R1`` and ``read R2`` in QUALITY FILTERING panel. 

  **Fix**: Check the input fastq file names and edit the identifiers. 
  Specify identifyer string that is common for all R1 reads (e.g. when all R1 files have '.R1' string, then enter '\\.R1'. 
  Note that backslash is only needed to escape dot regex; e.g. when all R1 files have '_R1' string, then enter '_R1'.). 

____________________________________________________

.. admonition:: "Error rates could not be estimated (this is usually because of very few reads). Error in getErrors(err, enforce = TRUE) : Error matrix is null."
  :class: error
  
  |learnErrors_fewReads|

  **Possible reason**: Too small data set; samples contain too few reads for DADA2 denoising.

  **Fix**: use OTU workflow.

____________________________________________________

.. error::

 Conflict. The container name XXX is already in use by container "XXX".
 You have to remove (or rename) that container to be able to reuse that name.

**Reason**: Process stopped unexpectedly and docker container was not closed.

**Fix**: Remove the docker container (not image!) that is causing the conflict

____________________________________________________

|

.. _bugs:

Known bugs
==========

**UNOISE**: chimeric sequences are removed from the zOTUs but not from the zOTUs table.
**Fixed in v1.1.0**

__________________________________________________

**QualityCheck** module: multiQC does not merge fastqc reports into a single multiqc_report.html file.
**Fixed in v1.1.0**

__________________________________________________

**Demultiplexing with dual indexes** in v1.1.0 only: samples names are eg indexF_1-indexR_1.fastq.gz.
**Fixed in v1.2.0**

__________________________________________________

**Icon are missing**, noted in v1.1.0. Try closing the GUI and opening it again to re-load the icons.
**Fixed in v1.2.0**