CRISPR troubleshooting

CRISPR troubleshooting

This page helps you diagnose the common failures across CRISPR guide design, off-target analysis, and screen hit calling — no guides or low on-target scores, too many or timed-out off-target sites, and screens that return no significant hits or format errors.

No guides returned for my target gene

Symptom: Guide design returns zero candidates.

Fixes:

• Check the gene symbol spelling. Use official HGNC symbols (e.g., TP53 not p53 or TRP53)
• If targeting a specific region, verify the genomic coordinates are correct and on the right assembly
• Relax the GC content filters. If min_gc is too high or max_gc is too low, valid PAM sites may be excluded
• Lower the min_score threshold. The default is 0.0 (no filtering), but if you set it higher, some targets with few PAM sites may have no qualifying guides
• For AT-rich regions with no NGG PAM sites, try AsCas12a (pam: "TTTV") which targets AT-rich sequences

All guides have low on-target scores

Symptom: Guides are returned but all have on-target scores below 0.4.

Fixes:

• Some genomic regions are inherently difficult to target due to sequence composition. This is expected for highly repetitive or GC-extreme regions
• Try a different PAM. SaCas9 (NNGRRT) or AsCas12a (TTTV) may find sites with better sequence context
• Target a different exon. Early constitutive exons often provide better guide candidates for knockout experiments
• Consider CRISPRi/CRISPRa approaches which are less dependent on cutting efficiency

Too many off-target sites reported

Symptom: Off-target analysis returns hundreds or thousands of sites.

Fixes:

• This is normal for 3-mismatch analysis of some guides. Focus on sites with 0-1 mismatches, which represent the highest risk
• Set include_cds_only: true to see only off-targets in coding regions (the most consequential sites)
• Reduce max_mismatches to 2 for a more focused analysis
• Choose a different guide. Guides with common seed sequences (PAM-proximal 12 nt) tend to have more off-targets
• Guides with repeated dinucleotides (e.g., ATATAT...) are prone to high off-target counts

Off-target analysis times out

Symptom: Off-target analysis fails with a timeout error.

Fixes:

• Reduce max_mismatches from 5 to 3 or lower. The search space grows exponentially with each additional mismatch
• Submit fewer guides at once. Analyze 1-3 guides per request instead of 10
• Use include_cds_only: true to reduce the search space

CRISPR screen analysis returns no significant hits

Symptom: MAGeCK analysis completes but no genes pass the FDR threshold.

Fixes:

• Increase the fdr_threshold from 0.25 to 0.5 as an initial exploration (note that higher FDR means more false positives)
• Verify that the correct sample columns are specified for control and treatment. Swapped labels will produce nonsensical results
• Check your count table for quality issues: guides with zero counts in all samples, missing genes, or inconsistent formatting
• Ensure you have sufficient replicates. Single-replicate screens have lower statistical power
• Verify the direction parameter matches your experiment. Use "negative" for essentiality screens and "positive" for resistance screens
• Weak selection pressure in the experiment itself (not a tool issue) is the most common cause of no hits

Screen analysis fails with format error

Symptom: Error message about invalid count table format.

Fixes:

• Ensure the count table has gene and guide columns (case-sensitive)
• Sample columns must contain only numeric values (integer read counts)
• Remove any header rows beyond the first (some export tools add metadata rows)
• Use comma (CSV) or tab (TSV) delimiters consistently. Do not mix delimiters
• Remove any trailing commas or empty columns
• Gene symbols must not contain commas or tabs

Guides target the wrong exon

Symptom: Designed guides are in an exon you did not intend to target.

Fixes:

• Use the exon_filter parameter to restrict guide design to a specific exon (e.g., "exon3")
• When using a gene symbol without an exon filter, guides are designed across all coding exons and ranked by on-target score
• For functional knockout, early constitutive exons (exons 2-4) are usually preferable

Getting help

If issues persist:

1. Check the tool error message for specific suggestions
2. Verify your input format matches the expected parameters
3. Try a known gene (e.g., TP53) to confirm the tool is working
4. Describe the issue to Ivy

Read next