---
title: Troubleshooting & Validation
description: Resolve XTalNet crystal structure prediction and polymorph screening issues.
tags:
  - xtalnet
  - troubleshooting
---

This page helps you diagnose common [XTalNet](/docs/xtalnet) problems across both tools — de novo crystal structure prediction from a SMILES string or PXRD pattern (`xtalnet_csp_predict`), and polymorph/co-crystal screening (`xtalnet_polymorph_predict`) — and walks through the validation steps and inputs to re-check before filing a ticket.

## Prediction issues

- **Job will not submit**: provide either a SMILES string, or PXRD data plus a compound formula — one of the two is required. See [inputs & restraints](/docs/xtalnet/inputs).
- **PXRD file rejected or misparsed**: files must contain angle (2θ), intensity pairs — comma, semicolon, or whitespace separated, with `#`/`//` comment lines. Check the data-point count and first-rows preview the tool shows after upload.
- **Too few or too many candidates**: the number of generated structures is set by **Number of Candidates** — 1–50 (default 10) for Crystal Structure Prediction, 10–50 (default 25) for Polymorph Screening. Raise the count if a single run misses the form you expect.
- **All predictions filtered out**: the **Min Confidence Threshold** (0–1, default 0.5) may be too strict for a noisy pattern — lower it to see more candidates, then triage manually.
- **Wrong crystal system**: constrain results with the optional crystal-system preference (cubic, tetragonal, monoclinic, and so on) when you already know the expected symmetry.
- **Co-crystal prediction fails**: `coformer_smiles` is only accepted by `xtalnet_polymorph_predict`, not `xtalnet_csp_predict` — run polymorph screening for co-crystal candidates.

## Validation steps

- Sort `xtalnet_csp_predict` results by `energy_kcal` in `energy_landscape_json`/`summary_csv` — the lowest-energy candidates are the most thermodynamically favorable.
- For polymorph screening, check `stability_rank` and `is_metastable` in `stability_ranking_json` before treating a form as viable long-term.
- Sanity-check the unit-cell atom count against **Max Atoms per Unit Cell** (default 400) — organic structures up to ~400 atoms are supported.
- Cross-check a predicted structure against reality by simulating its diffraction pattern with [PyWPEM](/docs/pywpem)'s `simulate_xrd` and comparing it to any experimental data you have.

## Inputs to re-check

- SMILES path: the SMILES string parses (it must use a restricted ASCII alphabet — letters, digits, brackets, ring-closure digits, bond and charge symbols).
- PXRD path: the compound formula matches the molecule, and the pattern's 2θ range and wavelength (`pxrd_metadata.wavelength`, default Cu K-alpha) are correct.
- Polymorph path: `num_candidates` is within 10–50, and `polymorph_similarity_threshold` (default 0.85) isn't so low that distinct forms collapse into one.

## Ticket checklist

- SMILES string, or PXRD data + compound formula.
- Tool used (`xtalnet_csp_predict` or `xtalnet_polymorph_predict`), candidate count, confidence threshold, and any crystal-system or coformer constraint used.
- The job's `jobId` and `status`, and any error message returned.

## Read next