错误码
*The interpretation of the Error Code part is only available in EN.
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:
| Error tag | Error type | Description |
|---|---|---|
| 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
| Error code | Error type | Interpretation |
|---|---|---|
| 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.: |
| 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
| Error code | Error type | Interpretation |
|---|---|---|
| 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
| Error code | Error type | Interpretation |
|---|---|---|
| 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
| Error code | Error type | Interpretation |
|---|---|---|
| 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
| Error code | Error type | Interpretation |
|---|---|---|
| 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
| Error code | Error type | Interpretation |
|---|---|---|
| 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
| Error code | Error type | Interpretation |
|---|---|---|
| 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.