---
title: CRISPR troubleshooting
description: >-
  Resolve guide design failures, excessive off-targets, and CRISPR screen
  analysis issues.
tags:
  - crispr
  - troubleshooting
---

## CRISPR troubleshooting

This page helps you diagnose the common failures across [CRISPR](/docs/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