Troubleshooting
Initial Check
Initial Check is conducted before commencing the actual analysis tasks. These checks involve verifying input datasets, including FASTQs, image(s), reference(s), optional arguments, the integrity of software packages, and the version information of dependency packages, among others.
If any issues are detected, the system will promptly report errors and exit, providing detailed feedback on the checks to prevent resource wastage. By default, the Initial Check function is enabled in the SAW count/realign pipelines. The parameter --no-initial-check has been introduced to control the use of this function.
...
2025-05-09 16:30:57 [runtime] (start:Initial Check) Performing Initial Checks of the analysis (please wait) ~
2025-05-09 16:30:57 [runtime] (run:Initial Check) Checking image files...
2025-05-09 16:31:25 [runtime] (run:Initial Check) Checking optional arguments...
2025-05-09 16:31:25 [runtime] (done:Initial Check) Initial Checks Finished!
2025-05-09 16:37:58 [library] numpy: 1.23.5
2025-05-09 16:37:58 [library] pandas: 1.5.3
2025-05-09 16:37:58 [library] numba: 0.58.1
2025-05-09 16:37:58 [library] seaborn: 0.13.0
2025-05-09 16:37:58 [library] matplotlib: 3.7.1
2025-05-09 16:37:58 [library] anndata: 0.9.2
2025-05-09 16:37:58 [library] tensorflow: 2.7.0
2025-05-09 16:37:58 [library] onnxruntime-gpu: 1.16.3
2025-05-09 16:37:58 [library] opencv-python: 4.8.0.76
2025-05-09 16:37:58 [library] stlib: 1.1.6
2025-05-09 16:37:58 [library] gefpy: 1.2.2
2025-05-09 16:37:58 [library] stereopy: 1.5.1
2025-05-09 16:37:58 [library] python: 3.8.19
2025-05-09 16:37:59 [library] bcSTAR: installed
...Error codes
SAW error codes are designed to capture error information and describe it in a straightforward manner. They are designed to express in three parts, date-time, error code, and explanation. The date-time information could help users distinguish errors in various program executions.
Under the /pipeline-logs directory, a stereo_log file will record the error information of pipelines if an error causes the program interruption. You can troubleshoot issues by combining the information from stereo_log .
Before using error code information to troubleshoot issues quickly, please ensure that the software version matches the manual you are referencing.
From SAW 8.2, the error codes and prompts have been optimized. The classification of error codes is based on the tag (last two digits) of the error code, like SAW-A10101. The specific classification and the description of each error type are shown in the table below:
01
Path and permission
Primarily due to missing input files, non-existent files, lack of access permissions, or incorrect output file paths, etc.
02
Content and format
Primarily due to issues such as files being unable to be read correctly, files failing to be parsed, incorrect file formats, missing file information, or errors encountered while writing files, etc.
03
Parameter setting
Primarily due to missing parameter settings, incorrect parameter types, or values exceeding the available range, etc.
04
Key metric and analysis output
Primarily due to abnormal analysis results, or abnormal key metrics, etc.
05
System resource
Primarily due to exceeding file storage limits, running out of memory, etc.
06
Processing logic
Primarily due to issues caused by code logic or underlying functionality.
07
Others
A small number of errors that do not fall into the aforementioned categories.
The first letter following "SAW-" indicates whether the error code belongs to
the workflow ("SAW_W00001"),
or the analysis tools ("SAW_A01001").
The beginning of an error prompt often includes keywords that provide a hint about the issue:
CANNOT ACESS: software can not get access to a specific file or directory.
IO ERROR: software meets some error when reading or writing a file.
PARSE ERROR: software finds someting wrong when parsing the content or format.
INVALID SETTING: input settings are not valid.
MISSING PARAMETER: certain parameters are missing.
RESOURCE NOT AVAILABLE: computing resources of the enviroment of not available or enough.
EXECUTION ERROR: something wrong happens when software is performing a specific function.
...
The following sectiosn will present examples of typical error codes and prompts encountered during the analysis.
The error code information is continuously being improved. If you encounter an unknown issue, please contact FAS/FBS for help.
Workflow
SAW-W00001
Path and permission
Please check your input datasets according the specific error message provided. e.g.: CANNOT ACCESS: Cannot find valid STAR reference directory in {STAR_path}. CANNOT ACCESS: FASTQ file not exist: {fastqs}.
SAW-W00002
Content and format
Please check if your input data format is correct or if the file is corrupted, etc.
e.g.: PARSE ERROR: The file '{filename}' has an invalid extension. Expected one of {valid_extensions} (File suffixes are not case sensitive). PARSE ERROR: Invalid fastq pairs: {fq1}, {fq2}.
SAW-W00003
Parameter setting
Please check if you have incorrectly entered parameters or omitted certain parameters, etc.
e.g.:
INVALID SETTING: Mismatch occurs in --sequencing-type and --kit-version. Find more information in SAW User Manual.
MISSING PARAMETER: Must input only one reference parameter in [--reference, --ref-libraries]
SAW-W00005
System resource
Please check the GPU resources, storage resources, and memory resources in your computing environment, etc. e.g.: RESOURCE NOT AVAILABLE: The GPU ID is not available: {gpu_id}. RESOURCE NOT AVAILABLE: Failed to check GPU status, the GPU ID is not available: {gpu_id}. Error: {e}.
SAW-W00006
Processing logic
Please make a judgment based on the location where the error occurred and the relevant log information. e.g.: EXECUTION ERROR: The program execution encountered an issue and has exited. Please check the log file: {log_file}. EXECUTION ERROR: Failed to building reference index.
Alignment of reads
SAW-A01001
Path and permission
Please check the input file exists and has the correct access permission.
e.g.:
CANNOT ACESS: --mask /path/to/chip/mask.
SAW-A01002
Content and format
Please check if your input data format is correct or if the file is corrupted, etc. e.g.: VERSION MISMATCH: The reference version does not meet the expectations, please check the reference file.
SAW-A01003
Parameter setting
Please check if you have incorrectly entered parameters or omitted certain parameters, etc. e.g.: INVALID SETTING: CIDMapping --mismatch %d > 3. Accept --mismatch is less or equal to 3.
SAW-A01004
Key metric and analysis output
Please check if your input data, upstream analysis results, or data quality are abnormal, etc. e.g.: ERROR: CID mapping rate-%lf is lower than the setting CIDMapping rateCutoff.
SAW-A01006
Processing logic
Please make a judgment based on the location where the error occurred and the relevant log information. e.g.: ERROR: The number of read1 and read2 parsed in readsbuf is not equal.
SAW-A03002
Content and format
Please check if your input data format is correct or if the file is corrupted, etc. e.g.: PARSE ERROR: -m {barcodeToPos_H5}. Only support .h5 suffix chip mask file.
SAW-A03005
System resource
Please check the GPU resources, storage resources, and memory resources in your computing environment, etc. e.g.: RESOURCE NOT AVAILABLE: Memory allocation calloc() error.
Annotation of reads
SAW-A02001
Path and permission
Please check the input file exists and has the correct access permission. e.g.: CANNOT ACESS: --sat_file {file_name}.
SAW-A02002
Content and format
Please check if your input data format is correct or if the file is corrupted, etc. e.g.: IO ERROR: Failed to write BAM. IO ERROR: Failed to create directory, directory already exists: {path}.
SAW-A02003
Parameter setting
Please check if you have incorrectly entered parameters or omitted certain parameters, etc. e.g.: INVALID SETTING: {thread_num} < 8. Minimum core number requires 8.
SAW-A02006
Processing logic
Please make a judgment based on the location where the error occurred and the relevant log information. e.g.: ERROR: Found duplicated geneID {gene_id}. ERROR: Failed to map block file: {file_name}.
SAW-A02102
Content and format
Please check if your input data format is correct or if the file is corrupted, etc. e.g.: PARSE ERROR: Input file should be in GTF/GFF format, suffixed with .gff/.gff.gz, .gff3/.gff3.gz, .gtf/.gft.gz. PARSE ERROR: Annotation records from multiple sites contain the same gene ID information.
Image processing
SAW-A04001
Path and permission
Please check the input file exists and has the correct access permission. e.g.: CANNOT ACESS: {file_path}.
SAW-A04002
Content and format
Please check if your input data format is correct or if the file is corrupted, etc. e.g.: PARSE ERROR: Cannot find attribute 'StainType' in IPR QCInfo. UNEXPECTED FORMAT: Invalid TAR.GZ. Found multiple IPR {ipr_files}./Cannot find IRP.
SAW-A04003
Parameter setting
Please check if you have incorrectly entered parameters or omitted certain parameters, etc. e.g: MISSING PARAMETER: --sn.
SAW-A04006
Processing logic
Please make a judgment based on the location where the error occurred and the relevant log information. e.g.: ERROR: IPR "{group} -> QCInfo" attribute "QCPassFlag" is less than 1. Cannot perform automatic registration. ERROR: The stitched FOVs image cannot be found under the {self.img_path}.
Expression matrix
SAW-A05001
Path and permission
Please check the input file exists and has the correct access permission. e.g.: CANNOT ACESS: {file_path}.
SAW-A05002
Content and format
Please check if your input data format is correct or if the file is corrupted, etc. e.g.: PARSE ERROR: -s {image_file}. Only file suffixed with TIFF are supported.
SAW-A05003
Parameter setting
Please check if you have incorrectly entered parameters or omitted certain parameters, etc. e.g: MISSING PARAMETER: -i {gef_file}.
SAW-A05005
System resource
Please check the GPU resources, storage resources, and memory resources in your computing environment, etc. e.g.: RESOURCE NOT AVAILABLE: Memory allocation calloc() error.
SAW-A05006
Processing logic
Please make a judgment based on the location where the error occurred and the relevant log information. e.g.: ERROR: TIFF size not equal to GEF size.
SAW-A06002
Content and format
Please check if your input data format is correct or if the file is corrupted, etc. e.g.: IO ERROR: Failed to open bin GEF file {file_name}. PARSE ERROR: Cannot find /cellBin/blockSize in file.
SAW-A06005
System resource
Please check the GPU resources, storage resources, and memory resources in your computing environment, etc. e.g.: RESOURCE NOT AVAILABLE: Cannot allocate memory for /wholeExp.
SAW-A06006
Processing logic
Please make a judgment based on the location where the error occurred and the relevant log information. e.g.: ERROR: Height and width of mask TIFF != Expression matix. TIFF:{height,width}. Expression matrix: {height,width}.
Secondary analysis
SAW-A07001
Path and permission
Please check the input file exists and has the correct access permission. e.g.: CANNOT ACESS: {file_path}.
SAW-A07002
Content and format
Please check if your input data format is correct or if the file is corrupted, etc. e.g.: PARSE ERRPR: Only -i/--input_file <GEF/GEM/H5AD> suffixed with .gef/.gem/.h5ad are supported.
SAW-A07003
Parameter setting
Please check if you have incorrectly entered parameters or omitted certain parameters, etc. e.g.: MISSING PARAMETER: --marker_mode
SAW-A07004
Key metric and analysis output
Please check if your input data, upstream analysis results, or data quality are abnormal, etc. e.g.: ERROR: Gene number less than 3000, please check your gef file.
SAW-A07106
Processing logic
Please make a judgment based on the location where the error occurred and the relevant log information. e.g.: ERROR: The "CellBin" or "cell" or "wholeExp" or {bin_size} field value is empty in file - {file_name}.
SAW-A13002
Content and format
Please check if your input data format is correct or if the file is corrupted, etc. e.g.: PARSE ERROR: The input feature expression {file} is not in a standard format and cannot be parsed.
SAW-A13006
Processing logic
Please make a judgment based on the location where the error occurred and the relevant log information. e.g.: ERROR: The calculation of Moran index is empty. Please check whether the bin size: {bin_size} in the {input_file} is abnormal. ERROR: The number of gene hotspots is zero. Please check whether the bin size of {bin_size} in the {input_file} is abnormal.
Report generation
SAW-A08002
Content and format
Please check if your input data format is correct or if the file is corrupted, etc. e.g.: PARSE ERROR: Attribute type class does not match expected type class. PARSE ERROR: Failed to open dataset: "/geneExp/bin1/expression".
SAW-A08006
Processing logic
Please make a judgment based on the location where the error occurred and the relevant log information. e.g.: PARSE ERROR: Total map reads less than pid mapped reads, please check file format from --bcstat.
SAW-A09001
Path and permission
Please check the input file exists and has the correct access permission. e.g.: CANNOT ACESS: {file_path}.
SAW-A09002
Content and format
Please check if your input data format is correct or if the file is corrupted, etc. e.g.: PARSE ERROR: Invalid saturation file format. PARSE ERROR: Please check quality control .xlsx file.
Access to help
Have any questions or concerns about the error codes fromyour SAW run?
Please get in touch with the local agents or FAS/FBS.
Last updated