---
title: GraphSol troubleshooting
description: Resolve invalid residues, length errors, fetch failures, and stuck jobs.
tags:
  - graphsol
  - troubleshooting
---

This page helps you diagnose the issues that most often interrupt a [GraphSol](/docs/graphsol) run — invalid residues, out-of-range sequence lengths, duplicate IDs, failed UniProt fetches, and jobs stuck in `running` — plus the quality checks to run before scaling up. GraphSol builds a graph from a predicted contact map, so most failures trace back to sequence integrity rather than the model itself.

## Input and validation errors

- **"Invalid residues"**: one or more sequences contain non-standard characters. Clean inputs to the 20-letter amino-acid alphabet (`ACDEFGHIKLMNPQRSTVWY`); remove ambiguous codes (`B`, `J`, `O`, `U`, `X`, `Z`).
- **"Sequence too long/short"**: keep sequences between **20 and 4,096 residues**. Split very long chains into domains, or check for a concatenation/translation-frame error on the shorter ones.
- **"Duplicate IDs detected"**: use unique FASTA headers, or disable deduplication explicitly if the duplicates are intentional controls.
- **File rejected on upload**: keep files under **25 MB**; gzip (`.gz`) is auto-detected. Split larger libraries into multiple jobs. See [preparing inputs](/docs/graphsol/inputs).

## UniProt fetch failures

- When you submit by UniProt ID, the sequence is fetched automatically; an unknown or malformed accession will fail that row.
- Verify the accession format (for example `P00533`) and that it resolves on UniProt before submitting.
- If a fetch is flaky, paste the FASTA sequence directly instead.

## Job stuck in `running`

- Check network stability and retry status polling with backoff; large batches can take several minutes.
- Feature generation (contact-map and profile features) is the heavy step — very large batches spend most of their time there.
- If a job exceeds 20 minutes for fewer than 5,000 sequences, treat it as a candidate ticket rather than continuing to wait.

## Quality checks

- Compare `summary.json` counts to your original file to confirm every sequence was processed.
- Scan the `warnings` column in `results.csv` for trimmed or filtered inputs.
- Re-run a small subset (5–10 sequences) to validate inputs before scaling to full batches.

## Interpreting borderline scores

- GraphSol returns a per-sequence probability (0–1) plus a binary call at a **0.5** default threshold; scores near 0.5 are genuinely ambiguous, not errors.
- For a consensus view, run [DeepSol](/docs/deepsol) on the same sequences — the two use different methods, so agreement raises confidence.
- Probabilities that appear constant across many diverse sequences point to an input problem (for example, every sequence failing feature generation), not real biology.

## When to contact support

- Repeated failures with clean FASTA files.
- Jobs exceeding 20 minutes for fewer than 5,000 sequences.
- Probability outputs that appear constant across many diverse sequences.

Include the `jobId`, submission time, and whether the input was gzipped when opening a ticket.

## Read next