UnicodeDecodeError: 'utf-8' codec can't decode byte 0xa6 in position 4: invalid start byte

[Cathaya-sasa]

Hello,

I’m using SAW version 8.2.0, and I encountered an error during the spatialcluster step. Could you please help identify what causes this? Any guidance or workaround would be greatly appreciated.Thank you very much for your help!

Here’s the relevant part of the log output:

SystemExit in file /home/software/SAW_8_2_0/saw-8.2.0/config/base.smk, line 1265:
Exit Snakemake program: The command Error: python /home/software/SAW_8_2_0/saw-8.2.0/lib/saw_cluster/main.pyc rna -i /data3/steroseq/S6/output/251107_S6/STEREO_ANALYSIS_WORKFLOW_PROCESSING/EXPRESSION_MATRIX/Y01104L8.tissue.gef -s 100 -r 1.0 --out_file /data3/steroseq/S6/output/251107_S6/STEREO_ANALYSIS_WORKFLOW_PROCESSING/ANALYSIS/Y01104L8.bin100_1.0.h5ad --report true >/data3/steroseq/S6/output/251107_S6/STEREO_ANALYSIS_WORKFLOW_PROCESSING/ANALYSIS/log_spatialcluster_100 failed to execute.
Error message: UnicodeDecodeError: 'utf-8' codec can't decode byte 0xa6 in position 4: invalid start byte
  File "/home/software/SAW_8_2_0/saw-8.2.0/anaconda/lib/python3.8/concurrent/futures/thread.py", line 57, in run
  File "/home/software/SAW_8_2_0/saw-8.2.0/config/base.smk", line 1265, in __rule_spatialcluster
  File "/home/software/SAW_8_2_0/saw-8.2.0/config/bioinformatics_utils.py", line 81, in run_spatial_cluster
  File "/home/software/SAW_8_2_0/saw-8.2.0/config/util.py", line 116, in run_command
Shutting down, this might take some time.
Exiting because a job execution failed. Look above for error message
[Tue Nov 11 02:39:45 2025]
Error in rule spatialcluster:
    jobid: 0
    input: /data3/steroseq/S6/output/251107_S6/STEREO_ANALYSIS_WORKFLOW_PROCESSING/EXPRESSION_MATRIX/Y01104L8.tissue.gef
    output: /data3/steroseq/S6/output/251107_S6/STEREO_ANALYSIS_WORKFLOW_PROCESSING/ANALYSIS/Y01104L8.bin50_1.0.h5ad
    log: /data3/steroseq/S6/output/251107_S6/STEREO_ANALYSIS_WORKFLOW_PROCESSING/ANALYSIS/log_spatialcluster_50 (check log file(s) for error details)

SystemExit in file /home/software/SAW_8_2_0/saw-8.2.0/config/base.smk, line 1265:
Exit Snakemake program: The command Error: python /home/software/SAW_8_2_0/saw-8.2.0/lib/saw_cluster/main.pyc rna -i /data3/steroseq/S6/output/251107_S6/STEREO_ANALYSIS_WORKFLOW_PROCESSING/EXPRESSION_MATRIX/Y01104L8.tissue.gef -s 50 -r 1.0 --out_file /data3/steroseq/S6/output/251107_S6/STEREO_ANALYSIS_WORKFLOW_PROCESSING/ANALYSIS/Y01104L8.bin50_1.0.h5ad --report true >/data3/steroseq/S6/output/251107_S6/STEREO_ANALYSIS_WORKFLOW_PROCESSING/ANALYSIS/log_spatialcluster_50 failed to execute.
Error message: UnicodeDecodeError: 'utf-8' codec can't decode byte 0xa6 in position 4: invalid start byte
  File "/home/software/SAW_8_2_0/saw-8.2.0/anaconda/lib/python3.8/concurrent/futures/thread.py", line 57, in run
  File "/home/software/SAW_8_2_0/saw-8.2.0/config/base.smk", line 1265, in __rule_spatialcluster
  File "/home/software/SAW_8_2_0/saw-8.2.0/config/bioinformatics_utils.py", line 81, in run_spatial_cluster
  File "/home/software/SAW_8_2_0/saw-8.2.0/config/util.py", line 116, in run_command
Shutting down, this might take some time.
Exiting because a job execution failed. Look above for error message
[Tue Nov 11 02:40:02 2025]
Finished job 15.
11 of 17 steps (65%) done
Shutting down, this might take some time.
Exiting because a job execution failed. Look above for error message
Complete log: /data3/steroseq/S6/output/.snakemake_.snakemake/log/2025-11-10T235622.113548.snakemake.log``

Command used:

saw count \
    --id=S6_count \
    --sn=Y01104L8 \
    --omics=transcriptomics \
    --kit-version="Stereo-seq T FF V1.3" \
    --sequencing-type="PE75_50+100" \
    --chip-mask=/data3/steroseq/S6/S6/mask/Y01104L8.barcodeToPos.h5 \
    --reference=/data3/steroseq/Reference/transcriptome/ \
    --fastqs=/data3/steroseq/S6/S6/reads/ \
    --image-tar=/data3/steroseq/S6/Y01104L8_SC_20251105_161628_4.1.2.tar.gz \
    --output=/data3/steroseq/S6/output \
    --unmapped-STAR-fastq \
    --create-gem \
    --skip-cellbin \
    --custom-bin-size=50,100 \
    --threads-num=100 \
    --memory=500 \
    --gpu-id=0

[Jinghao-Chen]

@Cathaya-sasa Hi, could you please send me the following files? If it's not convenient to send it via GitHub, you may consider sending it to my email address. chenjinghao@stomics.tech

/data3/steroseq/S6/output/251107_S6/STEREO_ANALYSIS_WORKFLOW_PROCESSING/ANNOTATION/Y01104L8.raw.gef
/data3/steroseq/S6/output/251107_S6/STEREO_ANALYSIS_WORKFLOW_PROCESSING/ANALYSIS/log_spatialcluster_50
/data3/steroseq/S6/output/251107_S6/STEREO_ANALYSIS_WORKFLOW_PROCESSING/ANALYSIS/log_spatialcluster_100

[Cathaya-sasa]

@Clouate Thanks for your reply! I have sent the relevant files to your email address.

[Jinghao-Chen]

Hi, the cause of the issue is that the Name of 5 genes in your GFF file contain garbled characters, which resulted in failed transcoding of these gene names during subsequent process analysis.

After transcoding, the corresponding character may be the Greek letter γ. Therefore, it's recommended that you first run the Python script in the attachment, input your tissue.gef file, and it will automatically correct the garbled parts to the string "gamma". Of course, you could modify it to other strings as needed.

After running the script, use the same saw count command to resume the analysis process from the breakpoint. And you could manually modify the garbled parts in the GFF file to avoid impacts on subsequent data analysis.

/home/software/SAW_8_2_0/saw-8.2.0/anaconda/bin/python change_str.py \

    /data3/steroseq/S6/output/251107_S6/STEREO_ANALYSIS_WORKFLOW_PROCESSING/EXPRESSION_MATRIX/Y01104L8.tissue.gef gamma

change_str.py