Start with the evidence you have
Troubleshoot a calculation
Start from the symptom that is present in the files, not from a guessed cause. Preserve the failed state, make the first discriminating check, and change one justified condition at a time.
This supporting index does not replace the A-E research workflow or software documentation. Program failure, solver convergence, observable convergence, physical validity, and a supported scientific claim remain separate questions.
The job does not start
The scheduler rejects the submission, leaves it pending, or records no application banner and no evidence that the requested executable launched.
Check this first
Read the submission receipt and current scheduler reason before inspecting QE settings. Confirm the cluster, job ID, owner, working directory, requested resources, and whether an output file exists or remains empty.
Inspect now
- Submission command and receipt, current queue state, pending reason, and detailed scheduler record
- Job script, working directory, stdout and stderr paths, modules, executable resolution, and input path
- Whether stdout or stderr exists, its size, and whether any program banner was written
- Account, partition, dependency, node, CPU, memory, time, and filesystem requests
Classify likely causes
- Invalid account, partition, reservation, dependency, or resource request
- Pending priority, unavailable nodes, maintenance, or site policy
- Missing job script, working directory, executable, module, permission, or input redirection
- Launcher or MPI integration failure before the application banner
Run a read-only quick check
Open the matching copy-ready Quick Reference check. Change only the declared OUT=...; read the complete files before deciding.
Read the official manual
Take the next safe action
- Wait when the scheduler record shows a valid pending reason that requires no correction.
- Otherwise correct only the demonstrated submission, path, environment, or resource fault and submit a new traceable attempt without changing the scientific input.
Show evidence to preserve and related workflow pages
Preserve before retry
- Job script, submission command and receipt, job ID, queue and detail records, stdout, and stderr
- Working directory, executable and module identity, input hash, resource request, and observation time
Related Research Workflow pages
The job stops before the calculation completes
The scheduler or launcher exits, the executable stops before its normal completion marker, or the output ends without a complete final electronic or ionic step.
Check this first
Read the scheduler state, exit code, standard output, and standard error together. Determine whether the executable launched, whether it read the input, and which program stage completed last.
Inspect now
- Scheduler state, exit code, resource record, and job-level error stream
- The first program banner and the last complete output block
- Exact executable, version, launch command, input path, and scratch identity
- Disk space, permissions, concurrent writers, and incomplete artifacts
Classify likely causes
- Launcher, module, shared-library, or MPI environment failure
- Malformed, empty, or incorrectly redirected input
- Wall-time, preemption, memory, disk, quota, or scratch failure
- Application-level fatal error after execution began
Run a read-only quick check
Open the matching copy-ready Quick Reference check. Change only the declared OUT=...; read the complete files before deciding.
Read the official manual
Take the next safe action
- Correct only the demonstrated environment, resource, input, or storage fault.
- If a diagnostic rerun is required, keep the scientific input unchanged and use isolated scratch with the smallest justified resource change.
Show evidence to preserve and related workflow pages
Preserve before retry
- Input, job script, job ID, launch command, standard output, and standard error
- Executable version, scheduler exit and resource record, and a hash or inventory of produced artifacts
Related Research Workflow pages
The input, pseudopotential, or method is rejected
The program reports an input-reading error, unknown keyword, missing file, incompatible pseudopotential family, or inconsistent exchange-correlation setup.
Check this first
Read the first fatal message against the input reference for the version that actually ran. Verify that the input is plain text and identify every pseudopotential or dataset exactly.
Inspect now
- The exact rejected namelist, keyword, tag, and preceding error context
- File type, line endings, paths, permissions, and referenced filenames
- Pseudopotential metadata, exchange-correlation identity, valence configuration, and hashes
- Charge, spin, occupation, and boundary-condition declarations
Classify likely causes
- Syntax or keyword mismatch between the input and software version
- Encoding, line-ending, path, permission, or empty-file problem
- Incompatible exchange-correlation and pseudopotential or dataset choices
- Invalid charge, spin, occupation, or boundary-condition specification
Run a read-only quick check
Open the matching copy-ready Quick Reference check. Change only the declared OUT=...; read the complete files before deciding.
Read the official manual
Take the next safe action
- Correct one evidenced input or compatibility fault at a time, using the documentation for the executed version.
- Do not force an override merely to make the parser continue when it changes the declared method.
Show evidence to preserve and related workflow pages
Preserve before retry
- The rejected input and complete error output
- Executable version and exact pseudopotential or dataset identities and hashes
Related Research Workflow pages
The electronic SCF cycle does not converge
The reported electronic residual does not reach its stopping condition, oscillates, rises after falling, or reaches the iteration limit.
Check this first
Audit the structure, electron count, charge, spin state, occupations, band count, and residual history before changing the mixer or eigensolver.
Inspect now
- Residual and total-energy trends over every electronic iteration
- Occupations, Fermi level, empty-state coverage, and k-point sampling
- Magnetization or other state labels and whether they change during the cycle
- Geometry, close contacts, warnings, and the exact stopping condition
Classify likely causes
- Implausible geometry, charge, spin state, or initial density
- Metallic occupation switching, too few empty states, or inadequate k-point sampling
- Long-wavelength charge sloshing or unsuitable density mixing
- Insufficient accuracy in the inner eigenproblem or an unsuitable solver
Run a read-only quick check
Open the matching copy-ready Quick Reference check. Change only the declared OUT=...; read the complete files before deciding.
Read the official manual
Take the next safe action
- First correct the model, state, occupations, band coverage, or sampling problem that the output demonstrates.
- Then test one documented mixer or eigensolver change in a bounded diagnostic run and return to the accepted numerical setup before interpreting a result.
Show evidence to preserve and related workflow pages
Preserve before retry
- Complete input and output, including the full iteration history and warnings
- Parent-state identity, restart ancestry, executable version, and hashes of reused artifacts
Related Research Workflow pages
The electronic SCF cycle becomes very slow
Electronic iterations continue but each iteration takes much longer than expected, output updates rarely, or diagonalization, FFT, communication, or I/O dominates the recorded timing.
Check this first
Confirm that the job is still active, then compare per-iteration timing, k points, bands, plane-wave size, process layout, memory, and I/O with one defensible smaller or earlier run before changing SCF algorithms.
Inspect now
- Scheduler state, elapsed time, CPU and memory record, output timestamps, and whether bytes are still advancing
- QE timing sections and iteration-by-iteration wall time, diagonalization count, and residual history
- Actual k points, bands, plane waves, FFT grids, pools, ranks, threads, and node placement
- Scratch location, file growth, filesystem health, competing writers, and environment or build changes
Classify likely causes
- A larger cell, cutoff, k mesh, band count, spinor problem, or symmetry reduction increased the actual workload
- Poor MPI or thread decomposition, oversubscription, load imbalance, or excessive communication
- Memory pressure, swapping, slow shared storage, checkpoint traffic, or filesystem contention
- An eigensolver or occupation problem increased inner iterations even though the outer SCF still advances
Run a read-only quick check
Open the matching copy-ready Quick Reference check. Change only the declared OUT=...; read the complete files before deciding.
Read the official manual
Take the next safe action
- Correct a demonstrated process-layout, memory, storage, or environment problem without changing the scientific model.
- If the workload itself grew, benchmark one small supported layout change and separately retain the convergence settings required by the observable.
Show evidence to preserve and related workflow pages
Preserve before retry
- Complete timing and iteration output, scheduler resource record, process layout, executable and library identity
- Exact input, k-point and band counts, cutoff and FFT settings, scratch inventory, and comparison-run identity
Related Research Workflow pages
The eigensolver, band count, or Fermi-level search fails
The output reports a diagonalization failure, unconverged eigenvectors, insufficient bands, or an inability to determine the Fermi level.
Check this first
Verify geometry, electron count, pseudopotential or dataset identity, occupations, k-point sampling, broadening, and band count before switching algorithms.
Inspect now
- Cell, coordinates, short distances, electron count, and charge
- Band count, final-state occupations, broadening, and k-point mesh
- Pseudopotential or dataset provenance and warnings
- Whether the same failure reproduces with another supported build or solver
Classify likely causes
- Invalid structure, electron count, charge, or pseudopotential or dataset
- Too few empty states or unsuitable occupations and broadening
- Too sparse a k-point mesh for the occupation treatment
- Numerical-library, build, or eigensolver failure
Run a read-only quick check
Open the matching copy-ready Quick Reference check. Change only the declared OUT=...; read the complete files before deciding.
Read the official manual
Take the next safe action
- Correct the structure, state, band coverage, occupations, or sampling first.
- Use a documented robust eigensolver only as a controlled diagnostic after the input objects are defensible.
Show evidence to preserve and related workflow pages
Preserve before retry
- The exact error with its preceding output context and complete input
- Pseudopotential or dataset hashes and executable, library, and build identities
Related Research Workflow pages
A restart or parent artifact cannot be read or trusted
The program cannot recover a calculation, rejects a restart, or a downstream task cannot find or read the expected density, wavefunction, save tree, or response artifact.
Check this first
Bind the artifact to its exact parent path, project or prefix, program version, termination state, representation, and hash before attempting reuse.
Inspect now
- Artifact inventory, size, hash, timestamp, and parent output
- Project or prefix, scratch directory, version, and sampling representation
- Parent termination and solver markers and the downstream reader's exact error
- Concurrent jobs or copied files that could have changed the artifact
Classify likely causes
- Incomplete or corrupt write from a failed parent run
- Wrong ancestry, path, project, prefix, or stale artifact
- Incompatible software version or Gamma-only versus k-point representation
- Concurrent jobs writing the same scratch identity
Run a read-only quick check
Open the matching copy-ready Quick Reference check. Change only the declared OUT=...; read the complete files before deciding.
Read the official manual
Take the next safe action
- Regenerate the artifact from an accepted parent or start from scratch when lineage or integrity cannot be established.
- Use restart conversion or reuse only where the official compatibility contract explicitly permits it.
Show evidence to preserve and related workflow pages
Preserve before retry
- A manifest and hashes of the failing artifact set and its parent output
- The failed reader output, exact paths, project or prefix, version, and launch command
Related Research Workflow pages
An expected output artifact is missing
A stage appears to have run, but the density, wavefunction, save tree, bands, DOS, projected data, dynamical matrix, force constants, table, or figure required for the next action is absent or empty.
Check this first
Name the exact executable and artifact its official output contract should produce, then bind the stdout, stderr, exit status, working directory, prefix or project identity, and parent artifacts for that one stage.
Inspect now
- Program banner, normal termination, shell and scheduler exit, stderr, and the last complete stage output
- Expected filename or directory from the version-matching manual and the exact input fields controlling it
- Working directory, prefix or project, outdir, file inventory, sizes, timestamps, hashes, and zero-byte files
- Parent completion and lineage plus cleanup, copy, archive, or concurrent jobs that could move or alter the object
Classify likely causes
- The stage did not reach the write point even though an earlier program or wrapper exited normally
- The artifact was written under a different working directory, prefix, outdir, filename, or format
- Disk, quota, permission, buffering, cleanup, or concurrent-writer failure left an absent or partial object
- The requested post-processing option did not produce the assumed artifact or the downstream filename was guessed
Run a read-only quick check
Open the matching copy-ready Quick Reference check. Change only the declared OUT=...; read the complete files before deciding.
Read the official manual
Take the next safe action
- Correct the demonstrated path, option, storage, or incomplete-stage problem and regenerate the artifact from the accepted parent.
- Do not create an empty placeholder, rename an unrelated file, or continue from an object whose writer and lineage are unknown.
Show evidence to preserve and related workflow pages
Preserve before retry
- Input, stdout, stderr, exit records, complete directory inventory, expected artifact definition, and parent manifest
- Working directory, prefix or project, outdir, software version, file hashes, and evidence of cleanup or concurrent writes
Related Research Workflow pages
Bands and DOS look inconsistent
A band plot suggests a gap or crossing while the DOS appears to show the opposite, Fermi levels or energy zeros do not align, or projected and total DOS features do not correspond as expected.
Check this first
Bind every plot and data file to its exact SCF and NSCF parent, sampling definition, number of bands, occupations, smearing, energy reference, spin channel, normalization, and post-processing executable before interpreting the difference.
Inspect now
- Exact parent manifests, prefix and outdir ancestry, structure, pseudopotentials, method, charge, spin and SOC settings
- Band path versus full-zone mesh, irreducible points, band count, occupations, smearing or tetrahedra, and DOS energy grid
- Fermi energy and plotted zero for every artifact, units, spin channels, normalization, broadening, and projection definitions
- Raw bands, total DOS and projected files together with program warnings such as unconverged eigenvalues
Classify likely causes
- The high-symmetry path misses a full-zone extremum or crossing sampled by the DOS mesh
- Bands and DOS use incompatible parents, structures, Hamiltonians, spin states, Fermi levels, or energy-zero conventions
- The NSCF mesh, band count, DOS grid, broadening, tetrahedron or smearing treatment is inadequate
- Projection labels, normalization, spin summation, interpolation, parser, or plotting columns are inconsistent
Run a read-only quick check
Open the matching copy-ready Quick Reference check. Change only the declared OUT=...; read the complete files before deciding.
Read the official manual
Take the next safe action
- First correct a demonstrated ancestry, reference, parser, normalization, or plotting mismatch without rerunning DFT.
- If the raw objects are compatible, run the smallest controlled full-zone, mesh, band-count, broadening, or energy-grid test required by the disputed observable.
Show evidence to preserve and related workflow pages
Preserve before retry
- SCF and NSCF inputs and outputs, post-processing inputs and outputs, raw bands and DOS data, plots, and parser version
- Parent hashes, k-point definitions, energy references, spin and normalization conventions, warnings, and convergence series
Related Research Workflow pages
I/O, memory, MPI, or scratch fails
The run reports an I/O error, segmentation fault, out-of-memory termination, disk or quota failure, or an intermittent parallel or network-filesystem error.
Check this first
Read the scheduler resource and exit record with standard error, then inspect disk space, quota, permissions, scratch identity, and concurrent writers.
Inspect now
- Scheduler state, peak memory, exit code, and node-level error messages
- Free space, quota, permissions, ownership, and scratch location
- MPI and library versions, process layout, and reproducibility across supported environments
- Concurrent processes, repeated project identities, and partial files
Classify likely causes
- Insufficient memory or stack and an unsuitable parallel decomposition
- Disk space, quota, permissions, or network-filesystem failure
- MPI, compiler, mathematical-library, or hardware incompatibility
- Two jobs sharing a project, prefix, filename, or scratch directory
Run a read-only quick check
Open the matching copy-ready Quick Reference check. Change only the declared OUT=...; read the complete files before deciding.
Read the official manual
Take the next safe action
- Correct the demonstrated resource, storage, parallel, or environment fault and give every run an isolated scratch identity.
- Do not continue from an artifact whose write integrity is uncertain.
Show evidence to preserve and related workflow pages
Preserve before retry
- Job ID, command, resource request, standard output, standard error, and host/software identity
- Scratch inventory, relevant file hashes, ownership, and the observed resource or storage limit
Related Research Workflow pages
The geometry looks physically wrong
A starting, intermediate, or final structure shows overlaps, broken coordination, an implausible cell, vacuum collapse, unexpected reconstruction, atom swapping, or motion inconsistent with declared constraints.
Check this first
Open the source, starting, suspect, and last accepted structures in the same viewer with the same cell, periodic-image, and orientation settings; confirm units, atom mapping, boundary conditions, and active constraints before changing optimizer settings.
Inspect now
- Source, initial, suspect, and final structures side by side, including cell vectors and periodic images
- Bond lengths, coordination, layer registry, vacuum, cell volume and angles, and constraint mapping
- Trajectory frames around the first anomalous change together with force, stress, displacement, and SCF histories
- Output warnings, state diagnostics, restart ancestry, and whether the suspicious frame was accepted by the optimizer
Classify likely causes
- Wrong structure source, unit conversion, atom order, periodic image, or coordinate convention
- Incorrect supercell, vacuum direction, cell degrees of freedom, symmetry, or constraints
- A real reconstruction or state-coupled distortion that must be tested rather than cosmetically repaired
- An unaccepted trial frame, failed electronic step, or corrupted or incompatible restart
Run a read-only quick check
Open the matching copy-ready Quick Reference check. Change only the declared OUT=...; read the complete files before deciding.
Read the official manual
Take the next safe action
- Stop using the suspect structure as a parent; return to the last accepted frame or rebuild the model from the verified source while preserving the anomalous branch.
- After correcting a demonstrated model, mapping, boundary, or numerical problem, run a bounded fresh energy-and-force check before restarting optimization.
Show evidence to preserve and related workflow pages
Preserve before retry
- Source, initial, suspect, and last accepted structures plus the complete trajectory and the viewer settings or screenshots needed to reproduce the observation
- Inputs, outputs, constraints, state labels, restart objects, and the exact transformation or manual edit applied
Related Research Workflow pages
The geometry optimization stalls or exits without an acceptable structure
The optimizer reports an error, reaches its step limit, repeats large moves, or exits without satisfying the active force and stress conditions.
Check this first
Verify electronic convergence at every ionic step, then inspect every free force component, relevant stress component, displacement, constraint, and electronic-state identity.
Inspect now
- The final complete force block and every active constraint
- Relevant stress components, geometry trajectory, step sizes, and objective history
- Electronic convergence and state identity at each ionic step
- Initial and final geometries, symmetry changes, and numerical settings that control force quality
Classify likely causes
- Noisy forces caused by insufficient electronic or numerical convergence
- Poor initial geometry, close contacts, or an unintended electronic state
- Incorrect constraints, relaxed degrees of freedom, or cell objective
- Floppy modes, excessive ionic steps, or inconsistent energy and force quality
Run a read-only quick check
Open the matching copy-ready Quick Reference check. Change only the declared OUT=...; read the complete files before deciding.
Read the official manual
Take the next safe action
- Run a fresh fixed-geometry electronic evaluation on the exact final coordinates and audit its forces, stress, and state.
- Correct force-quality, geometry, or degree-of-freedom problems before making one bounded optimizer or step-control change.
Show evidence to preserve and related workflow pages
Preserve before retry
- The complete trajectory, initial and final structures, constraints, and active degrees of freedom
- All inputs and outputs needed to bind force, stress, electronic state, and restart ancestry
Related Research Workflow pages
Forces remain large
One or more free Cartesian force components remain above the declared criterion, decrease and rebound, or disagree with the expected symmetry or structural motion.
Check this first
Read the last complete force block component by component against the exact input constraints. Keep the printed aggregate Total force separate, then verify electronic convergence and state identity for that geometry.
Inspect now
- Every final free Cartesian component, its units, the declared threshold, and all if_pos or equivalent constraints
- Force history, accepted and rejected trajectory frames, step sizes, close contacts, and symmetry changes
- SCF residuals, occupations, magnetization, warnings, and state continuity at each force evaluation
- Force sensitivity to the numerical dimensions required by the intended structural decision
Classify likely causes
- The structure is far from a stationary point, contains close contacts, or follows the wrong basin
- Electronic, cutoff, k-point, smearing, grid, or pseudopotential settings do not provide stable forces
- The intended free and fixed components, symmetry, or atom mapping do not match the executed input
- The electronic or magnetic state changes between ionic steps and makes the force surface discontinuous
Run a read-only quick check
Open the matching copy-ready Quick Reference check. Change only the declared OUT=...; read the complete files before deciding.
Read the official manual
Take the next safe action
- Correct a demonstrated model, constraint, state, or force-quality problem before restarting from the last accepted geometry.
- Use one fresh fixed-geometry energy-and-force evaluation to verify the exact candidate before another optimizer change.
Show evidence to preserve and related workflow pages
Preserve before retry
- Exact input, complete force blocks, constraints, trajectory, accepted-frame identity, and electronic-state diagnostics
- Software and pseudopotential identity, numerical settings, warnings, and the force criterion declared before the run
Related Research Workflow pages
Stress remains large
Relevant stress or pressure components remain outside the declared target, oscillate during a variable-cell run, or stay large in a fixed-cell diagnostic.
Check this first
Decide whether the cell was fixed or active, then read the last complete stress tensor with its units, sign convention, target pressure, and declared active cell degrees of freedom.
Inspect now
- The full final stress tensor, pressure, units and sign convention, not one scalar alone
- Cell_dofree or equivalent active cell variables, external target, cell history, volume, angles, and ionic coordinates
- Electronic convergence, force history, state labels, warnings, and accepted versus trial cell steps
- Stress sensitivity to the numerical settings required by the intended cell or equation-of-state decision
Classify likely causes
- A fixed or intentionally strained cell is not at its equilibrium stress and was never meant to relax
- The variable-cell objective, pressure target, cell constraints, symmetry, or cell representation is wrong
- Cutoff, FFT grid, k sampling, smearing, electronic threshold, or pseudopotential choices yield inadequate stress quality
- The structure or electronic state has not settled, or cell and ionic steps are poorly conditioned
Run a read-only quick check
Open the matching copy-ready Quick Reference check. Change only the declared OUT=...; read the complete files before deciding.
Read the official manual
Take the next safe action
- For a fixed cell, report stress as a diagnostic and change the cell only when the scientific protocol requires it.
- For an active cell, correct a demonstrated target, constraint, state, or stress-quality problem before one bounded restart from the last accepted cell.
Show evidence to preserve and related workflow pages
Preserve before retry
- Complete stress, force and cell histories, exact cell constraints, pressure target, units, sign convention, and trajectory
- Input, output, numerical settings, state diagnostics, restart ancestry, and accepted-cell identity
Related Research Workflow pages
Detected symmetry or k/q mapping differs from the intended model
The code finds fewer operations than expected, changes the irreducible mesh, reports a q-point star or degeneracy error, or identifies a different primitive-cell relation.
Check this first
Compare the exact cell, fractional coordinates, coordinate precision, and magnetic state with the operations reported by the code and with the declared computational model.
Inspect now
- Cell matrix, fractional coordinates, significant figures, species, and magnetic order
- Reported operations, primitive-cell relation, and irreducible k- or q-point sets
- The exact structure transformation and symmetry tolerance used before the run
- Whether cutoff or cell changes altered an automatically selected real-space grid
Classify likely causes
- Rounded coordinates, a rotated cell, or sites only approximately related by symmetry
- Primitive-versus-conventional-cell or supercell ambiguity
- A q point near but not exactly at the intended high-symmetry position
- Fractional translations, FFT-grid compatibility, or magnetic symmetry
Run a read-only quick check
Open the matching copy-ready Quick Reference check. Change only the declared OUT=...; read the complete files before deciding.
Read the official manual
Take the next safe action
- Correct or standardize the intentional model and regenerate every dependent k mesh, q mesh, and path.
- Do not disable symmetry merely to suppress a diagnostic without explaining the model change.
Show evidence to preserve and related workflow pages
Preserve before retry
- Source and transformed structures, transformation record, tolerance, and software version
- Before-and-after symmetry reports and all dependent sampling definitions
Related Research Workflow pages
The harmonic phonon calculation contains imaginary frequencies
One or more dynamical-matrix eigenvalues are negative, corresponding to imaginary phonon frequencies; some outputs or plots show these frequencies with a negative sign at Gamma or another q point.
Check this first
Classify acoustic and non-acoustic modes, q point, magnitude, and eigenvector, then audit the parent geometry, residual forces and stress, electronic convergence, and response convergence.
Inspect now
- Frequencies, eigenvectors, q-point identity, degeneracy, and whether the mode is acoustic
- Parent forces, stress, structure, electronic thresholds, and response thresholds
- k/q commensurability, q ledger or supercell, interpolation, masses, and non-analytic treatment
- Mode-displaced structures and convergence of the mode under controlled numerical changes
Classify likely causes
- Acoustic-sum-rule violation, interpolation artifact, or numerical noise
- Residual force, stress, or an insufficiently converged electronic parent
- Insufficient cutoff, k mesh, q mesh, supercell, or force-constant range
- Incorrect masses or data, or a genuine instability of the chosen structure
Run a read-only quick check
Open the matching copy-ready Quick Reference check. Change only the declared OUT=...; read the complete files before deciding.
Read the official manual
Take the next safe action
- Use an acoustic sum rule only as a diagnostic, then converge the parent state, response, and sampling and inspect the eigenvector.
- Recalculate on the accepted structure before following a mode or making a physical stability claim.
Show evidence to preserve and related workflow pages
Preserve before retry
- Parent and phonon inputs and outputs, dynamical matrices or force constants, and q-point ledger
- Mode eigenvectors, raw frequencies, interpolation settings, software version, and convergence series