Error Codes & Troubleshooting Guide

LymphoTrack Software – MiSeq provides error messages and log files to help laboratories quickly diagnose and resolve analysis issues.  Most errors can be resolved by verifying input file structure, naming conventions, or sequencing quality.

Best practices to prevent errors:

  • Verify input files:  Ensure paired FASTQ files (R1 and R2) and the correct sample sheet are present
  • Align file structure:  Remove spaces, symbols, and long paths (>255 characters)
  • Confirm requirements:  Review the latest LymphoTrack Software IFU version and verify the system meets the minimum requirements
    • Maintain at least 4 GB RAM and 20 GB free space before starting a run
  • Validate software compatibility:  Use instrument and software versions listed in associated IFUs.
  • Run only extracted and locally:  Verify the software is fully extracted and avoid using shared network drives

The content below provides descriptions and corrective actions for errors that may occur while running LymphoTrack Software, grouped into 3 functional areas:  

  • Software Execution & System Requirements
  • Input Data & File Structure Errors
  • Analysis & Reporting Errors

Software Execution & System Requirements

Includes installation, file permission, and system resource-related issues.

This error can occur due to 1 of the following 2 errors:
aaaaa

[Error-1]  

Description:
The software was unable to locate required parsed files during the calculation step (e.g., missing paired FASTQ fails or duplicate data sets with identical Sample IDs are in the same folder)
aaaaa

Corrective Action:   

  •    •     Verify that all paired FASTQ files (R1/R2) are present.
  •    •     Ensure no two datasets in the same folder share identical sample IDs.
  • aaaaa

aaaaa
[Error-2]

Description: 
When LymphoTrack Software v2.4.6 is installed in a folder path that contains spaces (e.g., C:Program Files); while spaces in input data folder paths are acceptable, the software cannot process installation paths containing spaces.
aaaaa

Corrective Action:
To resolve this issue, use Windows Command Prompt (administrator privileges may be required) to create a directory junction (i.e., a type of shortcut) that points to the installation folder but uses a path without spaces:

  1.    Locate or create a directory with no spaces in its path (e.g.,  C:MyOKDirectory)
    • →    The directory name does not matter as long as there are no spaces in the full path.
    • aaaaa
  2.    Open Command Prompt:  Right-click the Windows Start menu → select Command Prompt (Admin) or Windows Terminal (Admin).
    • aaaaa
  3.    Create the directory junction with the command below:
        mklink /J LymphoTrackMiSeq “C:Program FilesInvivoscribeLymphoTrackMiSeq-2.4.6.RUO”
    • →    This command creates a linked directory at:   C:MyOKDirectoryLymphoTrackMiSeq
    • aaaaa
  4.    Launch the LymphoTrackMiSeq-2.4.6.RUO executable file directly from the new junction directory.
    • →    Optionally, create a desktop shortcut or Start menu link to this executable.
    • aaaaa
  5.    Replace any previous shortcuts or links that point to the original installation directory containing spaces.
    • aaaaa

Application Notes:

Description:
Generic return code often caused by insufficient system memory or disk space.

Corrective Action:   

  • •     Ensure your system meets minimum specifications and that your local drive has sufficient free space.
  • •     Avoid running concurrent analyses.

Description:
This generic error indicates that a required executable could not be run properly, often due to permission or access restrictions in the installation or user Temp directories, resulting in the software unable to complete parsing and/or subsequent analysis steps.

Corrective Action: 
Verify that the following executables are allowed to run in both the installation folder and the user’s Temp folder:

  1.   Default Installation Paths
      The software installs by default into the following directory:         C:InvivoscribeLymphoTrackMiSeq-2.4.6.RUO
    • aaa
    • →       Required Executables
    • →        The corresponding main application executable must be unblocked:     LymphoTrackMiSeq-2.4.6.RUO.exe
      • aaaaa
    • →       Required Analysis Executables
      •  These self-extracting executables unpack and run dynamically during analysis and must not be blocked by the OS, antivirus/endpoint protection, or Group Policy.  All of the following executables must be permitted to execute.  Blocking any of them can stop parsing, merging, or calculation steps and trigger error code -1.
      • aaaaa
    • →       Normal executable:
      •     –   blastn.exe
      • aaaaa
    • →       Self-extracting executables:
      •   –   Calc_IGH_Leader_miseq.exe
      •   –   Calc_IGH_FR1_miseq.exe
      •   –   Calc_IGH_FR2_miseq.exe
      •   –   Calc_IGH_FR3_miseq.exe
      •   –   Calc_IGK_miseq.exe
      •   –   Calc_TRB_miseq.exe
      •   –   Calc_TRG_miseq.exe
      •   –   merge_IGH.exe
      •   –   merge_IGK.exe
      •   –   merge_TRB.exe
      •   –   merge_TRG.exe
      •   –   Parse_IGH_Leader.exe
      •   –   Parse_IGH_FR1.exe
      •   –   Parse_IGH_FR2.exe
      •   –   Parse_IGH_FR3.exe
      •   –   Parse_IGK.exe
      •   –   Parse_TRB.exe
      •   –   Parse_TRG.exe
      • aaaa
      • aaaaaa
  1.   User Temp Directory Requirements
    • →       Temp Directory Path
    • →       The software extracts and executes analysis components inside the directory defined by the system’s  %TEMP%  environment variable.
      •    –   Typical default:   %OSDRIVE%Users\AppDataLocalTemp
      •    –   (This path may differ depending on IT configurations such as roaming profiles)
        aaaa
    • →       Runtime Extraction Folders
    • →       During analysis, each self-extracting module generates subdirectories with the naming pattern:   par-cache-
    • →       aaa
      •    –   Example:     par-757365727870cache-71FA0109D8A2C10CF6B99C2661A08FC802B5E813
        •  •     There will be one or more  par-* directories per run
        •  •     Each will contain multiple  cache-*    
        •  •     These folders are temporary and unique for each execution cycle
        • aaaa
    • →       Required Execution Permissions in Temp Folders
    • →       Inside each  cache-* directory, the following must be allowed to run:
    • aaaaa
      •   •     All executables corresponding to the self-extracting modules (Calc, Parse, merge)
      •   •     All  DLL  files extracted into these directories
      •   •     Blocking any file in these folders may cause parse failures and trigger Parse error -1. 
      • aaaaa
      • aaa
  1.   Optional Configuration: Overriding %TEMP%
      Organizations may optionally redirect temporary extraction to a different directory by setting the environment variable:   PAR_GLOBAL_TEMP=
    • →       If this variable is used:
      •  •     All executables and  DLL files at the top level of the specified directory must be permitted to execute.
      •  •     The directory should not be write-restricted or monitored by cleaning utilities that remove subdirectories in real time.
      • aaaaa
      • aaaaa
  1.   IT and Security Team Considerations
    •  •     White-list the installation directory and the user’s Temp directory (or the directory defined by  PAR_GLOBAL_TEMP ).
    •  •     Ensure endpoint protection does not sandbox or block  EXE,  DLL, or self-extracting binaries.
    •  •     Avoid group policies that deny execution in user-level Temp paths.
    •  •     Confirm that real-time cleanup tools do not delete  par-*  or  cache-* folders while analysis is in progress.

Input Data & File Structure Errors

Covers file naming, folder structure, and input compatibility problems.

Description:
The FASTQ files were generated by an application other than the MiSeq Reporter (MSR) software
aaaaa

Corrective Action: 
Please refer to the MiSeq User Guide for more information
aaaaa

Application Notes:

  • •    The LymphoTrack Software – MiSeq expects paired-end FASTQ files generated by the MiSeq Sequence Reporter (MSR) software.   
  • •    If the MSR software was not used to generate the sequence files input to LymphoTrack Software, the analysis fails, providing the error message above.
  • •   aaaa
  • •    While other programs provide the same function as the MSR software (i.e., Bcl2fastq), these programs can apply different parameters, potentially  •    generating different base calls as compared to the MSR software analysis.  LymphoTrack Software requires that the base-calling is performed using the MSR software.   The LymphoTrack Assay results are only valid when analyzing FASTQ files generated with the MSR software.

Description:
Indicates one or more FASTQ files were corrupted during data transfer or before compression completed.

Corrective Action:   

  • •    Re-transfer data from the MiSeq Run Folder after ensuring the instrument has fully completed compression
  • •    (wait ≥30 minutes after “Sequencing Completed”) system meets minimum specifications and that your local drive has sufficient free space.
  • •   
  • •     Remove corrupted files from the folder before analysis.
  • aaa

Application Notes:
The Undetermined*_.FASTQ.GZ file should not be included in analyses, as it contains unassigned reads.

Description:
This error occurs when the software cannot properly pair FASTQ files or recognize sample naming formats.

Corrective Action:   

  • •     Ensure sample names conform to MiSeq Reporter convention and do not include extra identifiers such as run names.
  • •     Example of correct naming:     [R1]:  SampleName_S1_L001_R1_001.fastq.gz   |   [R2]:  SampleName_S1_L001_R2_001.fastq.gz  
  • aaa

Application Notes:

  • •    This error may be caused by additional suffixes (e.g., “_RunName”) added during FASTQ generation.
  • •    Re-run demultiplexing using the MiSeq Reporter Software, if necessary.

Description:
The directory folder name conflicts with a sample name.

Corrective Action: 
Rename the analysis folder so it is different from any contained sample name, then re-run the analysis.

Description:
FASTQ file names do not match the expected MiSeq Reporter naming convention.

Corrective Action:   

  • Rename files using the format:
  • [R1]:  SampleName_S1_L001_R1_001.fastq.gz   |   [R2]:  SampleName_S1_L001_R2_001.fastq.gz
  • aaa

Application Notes:

  • •    Only MiSeq-generated FASTQ files are supported.
  • •    Demultiplexing must be performed through MiSeq Reporter, not older versions of bcl2fastq or other software.  
  • •    Refer to the MiSeq Reporter Software Guide for the correct file format.

Description:
Indicates a generic parsing failure caused by missing or misnamed FASTQ files, mismatched paired-end files, or incomplete data transfer.

Corrective Action:   

  • •    Verify that all paired FASTQ files (R1/R2) are present.
  • •    Ensure no two datasets in the same folder share identical sample IDs.
  • •    Confirm all file names follow MiSeq Reporter naming format:
  • •    [R1]:   SampleName_S1_L001_R1_001.fastq.gz and [R2]:   SampleName_S1_L001_R2_001.fastq.gz.
  • •    Ensure files are stored locally (not on a network drive).
  • aaa

Application Notes:

  • •    Check that your system meets the minimum requirements according to the most recent IFU version.
  • •    Avoid using folder names identical to sample names.

Analysis & Reporting Issues

These are failures that can occur during calculation, result compilation, or report generation.

Description:
The software cannot process analysis when both FASTQ and FASTQ.GZ files exist in the same folder, or when unrelated files are present.
aaaaa

Corrective Action: 

  • •    Use an empty local folder containing only the FASTQ files to be analyzed.
  • •    Ensure all files are either uncompressed (FASTQ) or compressed (FASTQ.GZ)—not mixed.
  • aaaaa

Application Notes:

  • •    Refer to latest IFU version for folder setup guidelines.   
  • •    Copy only the required FASTQ files into the analysis folder.

Description:
Output files indicate fewer reads than expected; positive control does not indicate the correct clonal rearrangement.
aaaaa

Corrective Action: 

  • 1. Verify that Adapter Trimming was properly applied during run setup and processing.
    • •    If necessary, re-queue the run with a corrected Sample Sheet that ensures Adapter Trimming is enabled.
      aaaaa
  • 2. Confirm that FASTQ files were generated using MiSeq Reporter prior to LymphoTrack Software analysis.
    • •    Ensure all files are either uncompressed (FASTQ) or compressed (FASTQ.GZ)—not mixed.
      aaaaa

Application Notes:

  • •    LymphoTrack Software is validated only for use with FASTQ or FASTQ.GZ files generated by MiSeq Reporter.
  • •    Use of alternative de-multiplexing tools may result in suboptimal read counts or unexpected analysis results.

Description:
The software was unable to generate the final PDF report (may occur in LymphoTrack Software – MiSeq versions preceding v2.4.6 and LymphoTrack Software – S5/PGM versions preceding v2.4.10.
aaa

Corrective Action: 
Follow generic troubleshooting for parsing errors: verify FASTQ integrity, naming, and file completeness.
aaa

Application Notes:

  • •    Verify all required analysis files are present.
  • •    Confirm that decimal formatting uses a decimal point, not a comma, in system regional settings.
  • •    Ensure all files are stored locally and not within compressed folders.

*LymphoTrack Software – S5/PGM version 2.4.10 and later as well as LymphoTrack Software – MiSeq versions v2.4.6 and later will not indicate this error since Java is no longer required.

Description:
The analysis halts unexpectedly due to insufficient memory or disk space.
aaaa

Corrective Action:   

  • •    Ensure the analysis is run on a local drive with adequate space.
  • •    Confirm all minimum requirements are met, per the most recent IFU version.  
  • •    Close other programs before running analysis.
  • aaa

Application Notes:

  • •    Avoid running analyses on shared or network drives.
  • •    Save and back up all input data before re-running.

Description:
Running the software simultaneously on a shared network or server can cause permission conflicts and analysis failures.
aaa

Corrective Action: 
Run analyses locally on individual computers rather than shared servers.
aaa

Application Notes:   

  • •    Concurrent sessions are not supported.
  • •    Network permissions may prevent proper execution.

Need Help Resolving an Error?

If the issue persists after these checks, our technical team can help.  Please contact Invivoscribe Technical Support with your error code, log file, and software version:  [email protected]

Tip:   When contacting support, please include:

    • +     The log file* from the failed run
    • +     LymphoTrack Software version
    • +     Sequencing platform and instrument software version
    • +     Screenshots of folder structure and/or error messages
    • aaaaa
  • *Each analysis automatically generates a log file (e.g., LymphoTrackMiSeq.log) containing timestamps, parameters, and error details.

Disclaimer

LymphoTrack Software is for RESEARCH USE ONLY (RUO).   Not intended for diagnostic purposes.