Example Error Messages

Failed to read file '/path/to/input.xyz': No such file or directory

Invalid syntax at line 3: Unknown element symbol: Xx

SCF failed to converge after 100 iterations (ΔP = 1.23e-05)

Matrix is singular or nearly singular (condition number: 1.23e+15).
The matrix is ill-conditioned during symmetric orthogonalization.
Possible causes: (1) Linear dependence in basis set, (2) Atoms too close together

Common Errors and Solutions

ErrorLikely CauseSolution
ParseError: Invalid syntax at line NTypo in input fileCheck line N for syntax errors
BasisError: Basis set not foundTypo in basis name or missing basisCheck basis name spelling; see available basis sets
ScfError: failed to convergeDifficult convergenceIncrease MaxCycle, add Shift, try XQC/YQC
LinalgError: singular matrixLinear dependenceUse smaller basis, check for duplicate atoms
NumericalError: NaN/InfNumerical overflowCheck geometry, reduce step size

Debugging Tips

  1. Enable trace output for DIIS/BFGS:

    OPENQ_DIIS_TRACE=1 oquantum input.inp
OPENQ_BFGS_TRACE=1 oquantum input.inp

  2. Check geometry for:

    • Atoms too close together (< 0.5 Å)
    • Linear dependencies in basis
    • Incorrect coordinates

  3. Try alternative SCF methods:

    • XQC for DIIS + QC fallback
    • YQC for SD → DIIS → QC chain
    • QC true for full QC-SCF