rlaplaza and crew at the IIQ in Seville

ORCA Basics and Troubleshooting

rlaplaza January 01, 2026 October 05, 2026
tutorial computational-chemistry orca troubleshooting

ORCA Basics and Troubleshooting

This guide starts with a short tutorial on how to write and run a basic ORCA job—input layout, parallelism and memory, and geometry optimization for minima and transition states. The second half is a troubleshooting catalog for common failures. The companion Gaussian Basics and Troubleshooting guide covers the same topics for Gaussian. For background on how the SCF works in practice (scaling, integrals, guesses, convergence accelerators, and analytical gradients), see SCF in Practice. Advice below is rooted in the official ORCA FAQ and manuals rather than forum folklore.

Tip: Use your browser’s search function (Ctrl+F / Cmd+F) to jump to a specific error. The ORCA FAQ and the SCF/geometry sections of the manual are the best reference points for troubleshooting.

Basic input file

A minimal ORCA input has three pieces: a keyword line (method, basis, and job type), optional resource blocks, and a coordinate block with charge and multiplicity.

! B3LYP D3BJ def2-SVP Opt Freq TightSCF

%pal
  nprocs 4
end

%maxcore 2000

* xyz 0 1
O   0.000000   0.000000   0.117300
H   0.000000   0.757200  -0.469200
H   0.000000  -0.757200  -0.469200
*

London dispersion is critical for organics, noncovalent contacts, and many reaction energetics, yet it is missing from most hybrid functionals (including bare B3LYP and PBE0). Add an empirical correction such as D3BJ or D4, or use a functional that already includes nonlocal correlation.

For cluster submission helpers that read %pal / %MaxCore from the input, see Using Agustina.

Practical starting points in ORCA (always with dispersion unless the functional already includes it):

Useful DFT benchmark and method papers:

Prefer the Karlsruhe def2 family for DFT work:

These sets were designed with DFT (and HF/MP2) in mind, are balanced across much of the periodic table, and pair heavier elements with Stuttgart effective core potentials so you do not need a separate all-electron treatment for most mid-to-late-row atoms. The examples in this guide use def2-SVP for routine jobs and def2-TZVP when a larger basis is illustrated.

The original design and accuracy assessment across a large molecular test set is in Weigend and Ahlrichs (2005).

Parallelism and memory

ORCA parallelizes with MPI. %pal nprocs N asks for N processes. %maxcore is the memory dedicated to each process (in MB), not the total for the job.

Rough total memory:

total ≈ nprocs × maxcore

Match these to your scheduler allocation. If you request 8 processes and %maxcore 2000, plan on roughly 16 GB of RAM for ORCA alone, plus a little headroom for the OS and the queue. Oversubscribing (more processes than memory allows) is a common cause of Please increase MaxCore aborts—covered in the troubleshooting half below.

Example that asks for 4 cores and 2 GB per process:

%pal
  nprocs 4
end
%maxcore 2000

If memory is tight, reduce nprocs before cutting the method or basis. More cores do not always help if each process is starved of memory.

Optimizing minima

For a ground-state minimum, add Opt to the keyword line. A common pattern is to optimize and then compute frequencies in one job so you can confirm there are no imaginary modes:

! B3LYP D3BJ def2-SVP Opt Freq TightSCF

Useful %geom controls when a structure is floppy or slow to settle:

%geom
  MaxIter 100
  coordsys redundant
  cartfallback true
end

What “done” looks like: the optimization reports that the geometry has converged, the SCF is tight, and a subsequent frequency job shows zero imaginary frequencies for a true minimum. If the optimizer stalls or the structure looks chemically wrong, see the geometry sections in the troubleshooting half rather than blindly raising MaxIter.

Optimizing transition states

A transition state (TS) maximizes the energy along one Hessian mode and minimizes along the others. In ORCA that is OptTS, usually with an explicit Hessian and mode selection:

! B3LYP D3BJ def2-SVP OptTS Freq TightSCF

%geom
  TS_Mode {M 0} end
  Calc_Hess true
  Recalc_Hess 5
end

Practical checklist:

  1. Start from a good guess (often from a relaxed surface scan along the reaction coordinate).
  2. Compute or refresh the Hessian (Calc_Hess / Recalc_Hess) so the optimizer follows the intended mode.
  3. After convergence, run frequencies and confirm exactly one imaginary mode that matches the reaction coordinate.

If the job collapses to a minimum or follows the wrong mode, the TS troubleshooting section below covers the usual next steps.

When a calculation fails or behaves oddly, use the catalog below. Search for the error text or the symptom that matches your output.

Troubleshooting common issues

Memory and Resource Issues

“Please increase MaxCore”

Common symptom:

What the official guide says: The ORCA FAQ states that the SCF may need more memory than the user-specified MaxCore and that newer ORCA versions estimate the memory requirement early in the calculation. If the estimate is larger than MaxCore but smaller than 2*MaxCore, ORCA gives a warning and continues. If it is larger than 2*MaxCore, the job aborts. The FAQ also notes that MaxCore is the memory dedicated to each process, not the total job memory.

Practical fixes:

  1. Increase the per-process memory in the job script or launch command.
  2. Reduce the number of MPI processes if memory per process is too low.
  3. Re-check whether the job is overcommitted on memory.

Example:

! B3LYP D3BJ def2-TZVP TightSCF
%maxcore 2000

SCF Convergence Issues

For the conceptual background (guesses, DIIS, SOSCF, direct vs conventional integrals), see SCF in Practice. The recipes below are ORCA-specific.

SCF does not converge

Common symptoms:

What the official guide says: The ORCA SCF convergence chapter explains that convergence is a major practical issue in quantum chemistry. It documents convergence tolerances, damping, level shifting, DIIS, and the TRAH algorithm. It also notes that if the integral accuracy is worse than the SCF tolerance, a direct SCF calculation cannot converge properly.

Practical fixes:

  1. Start with a more robust SCF level: 
    ! TightSCF

    or

    ! SlowConv
  2. Use damping or level shifting early in a difficult calculation: 
    %scf
  CNVDamp true
  DampFac 0.7
  DampErr 0.001
end

  3. Increase the maximum number of SCF cycles if needed.

  4. For hard cases, allow the automatic TRAH fallback: 
    %scf
  AutoTRAH true
end

The SCF manual specifically states that TRAH is useful when the conventional SCF procedures struggle.

Open-shell or near-degenerate systems

Common symptoms:

What the official guide says: The ORCA FAQ and SCF section emphasize that open-shell systems, especially transition-metal complexes, can be difficult. The guidance recommends checking S^2, UCO overlaps, and spin populations to confirm that the solution is meaningful.

Practical fixes:

  1. Confirm the charge and multiplicity are chemically reasonable.
  2. Try a better initial guess.
  3. Use a more restrictive convergence setting for difficult electronic structures.
  4. Inspect the resulting electronic structure rather than trusting a “converged” number blindly.

Geometry Optimization Issues

Optimization stalls or fails to converge

Common symptoms:

What the official guide says: The ORCA geometry optimization chapter explains that optimization can be difficult even when the underlying method is valid. It also notes that floppy structures with many rotations around single bonds or soft dihedral modes are especially challenging. The manual describes the role of the initial Hessian, step type, and coordinate system in convergence.

Practical fixes:

%geom
  MaxIter 50
  Step qn
  Trust 0.3
  coordsys redundant
  cartfallback true
end
  1. Check the starting geometry.
  2. Use a better initial Hessian or a more suitable coordinate system.
  3. If the optimization is problematic, revisit the starting structure instead of assuming the failure is purely numerical.

Transition state optimization fails or follows the wrong mode

Common symptoms:

What the official guide says: The ORCA geometry optimization section explains that TS optimization is a separate problem: it maximizes the energy along one Hessian eigenmode while minimizing along the others. It also discusses TS_Mode, Hessian updates, and relaxed scans for TS optimization.

Practical fixes:

! OptTS
%geom
  TS_Mode {M 0} end
  Calc_Hess true
  Recalc_Hess 5
end
  1. Use an explicit TS setup.
  2. Use a relaxed surface scan to locate the relevant reaction coordinate before TS optimization.
  3. Confirm that the final structure has exactly one imaginary mode.

Atoms merge into each other during optimization

Common symptom:

What the official guide says: The ORCA FAQ explicitly states that this usually occurs due to a poor or wrong initial molecular-orbital guess or a bad basis-set definition on the relevant atoms. The advice is to check the basis set on the problematic atoms and then the corresponding MOs.

This is a good example of an ORCA-specific issue: the problem is not a generic optimizer bug, but a quality-of-initial-guess and basis-definition issue.

Frequency Calculation Issues

Frequencies fail when the wavefunction is not converged

Common symptoms:

What the official guide says: The SCF chapter is explicit: properties and numerical calculations, including NumGrad and NumFreq, are not performed on non-converged wavefunctions.

Practical fixes:

  1. Ensure the SCF is converged before asking for frequencies.
  2. Use a tight SCF and a well-converged geometry before Freq.
  3. If necessary, optimize first and then compute frequencies in the same workflow: 
    ! B3LYP D3BJ def2-TZVP Opt Freq

File and I/O Problems

MOREAD says that no orbitals were found in the .gbw file

Common symptom:

What the official guide says: The ORCA FAQ explains that ORCA writes the .gbw file immediately after reading the geometry and basis set information. If a stale .gbw file with the same basename remains in the working directory, it can be overwritten or interfere with the current calculation. The recommendation is to rename the old file before rerunning.

Practical fix:

mv oldjob.gbw oldjob.gbw.old

Old inputs stop working after a version upgrade

Common symptom:

What the official guide says: The FAQ explicitly states that keywords and defaults may change between ORCA versions, and the same input may give slightly different results or fail entirely. The recommendation is to consult the current manual and release notes instead of assuming the old input remains valid.

Installation and Launch Issues

ORCA is installed but the program does not start

Common symptoms:

What the official guide says: The FAQ explains that ORCA is invoked from the command line on all platforms and gives the standard launch pattern:

<full orca binary folder path>/orca example.inp > example.out

It also explains the installation process for Linux/macOS: the .run installer is made executable with chmod a+x, followed by execution of the installation script.

Practical fixes:

  1. Verify that the ORCA executable is on PATH.
  2. Check that the working directory is the one expected by the script.
  3. Run a minimal test calculation before moving to a large job.

A good ORCA triage checklist

Sources

These are the official ORCA documentation pages used as the verified basis for the advice above.

Previous post
Gaussian Basics and Troubleshooting Next post
Vi and Vim Basics