Custodian Error Handlers

Custodian uses different error handlers to check and correct for different failures of VASP calculations. Thus, one can individually decide which error should be corrected and which error should fail the calculation and connect the corresponding handlers. Error handlers for the calculations run with the calculation classes implemented in this plugin can be passed via the inputs.custodian.handlers input. Here, the input is expected to be a dictionary of the following form:

 handler_inputs = {
    'HandlerName1': {
        'option': 'value',
    'HandlerName2': {
        'option', 'value',

In that case every dictionary entry corresponds to an individual handler specified by its name and the corresponding handler options to be used for it. Note if an empty dictionary is passed as option to any handler, i.e. ‘HandlerName’: {}, the plugin’s default options are used for the handler. Since one often wants to use the defined default for all handlers in the first place handlers may also be passed as a simple list of handler names. In that case the default values are used for every defined handler and the example above would simplify to

handler_inputs = ['HandlerName1', 'HandlerName2', ...]

In the following all handlers available for VASP calculations are described in more detail and the available settings and their used defaults are shown. (For more complete overview please refer to the original Custodian documentation)


Most basic error handler for VASP calculations checking for the most common VASP errors logged to the stdout output (i.e. Call to ZHEGV failed, TOO FEW BANDS, etc.) (See also VaspErrorHandler)

Handler Settings:

  • natoms_large_cell (int) – Number of atoms above which a structure is considered as large. This has implications on the strategy of resolving some kind of the errors (for instance whether LREAL should be set to True or False, etc.) (default: 100)

  • errors_subset_to_catch (list) – List of errors that will be caught (other errors not in the list are ignored!). If set to None all errors known to the handler will be detected. (default: None)


    A complete list of errors known to the handler that may be passed in this list can be directly found from the VaspErrorHandler:

    >>> from custodian.vasp.handlers import VaspErrorHandler
    >>> known_errors = list(VaspErrorHandler.error_msgs.keys())
    >>> for error in known_errors:
    ...    print(error)


Considers a calculation as frozen if the output to stdout is not updated for a defined amount of time and restarts the job if frozen. (See also FrozenJobErrorHandler)


If using this handler do not set the timeout too low for demanding calculations with many atoms and / or a dense kpoint grid!

Handler Settings:

  • timeout (int) – Seconds without activity on the stdout output after which the job is considered as frozen (default: 21600)


Check for positive energy changes in electronic steps (dE) larger than the defined threshold and reduce POTIM parameter accordingly.

Handler Settings:

  • dE_threshold (float) – Maximum threshold (in eV) for energy changes between consecutive electronic steps. For energy changes larger than the defined value the handler will restart the calculation with reduced POTIM parameter (default: 1.0)


Check if NELM is reach for nionic_steps consecutive ionic steps and correct by first switching to more stable algorithms (ALGO) and secondly adjusting the mixing parameters (AMIX, BMIX, BMIN). (See also NonConvergingErrorHandler)

Handler Settings:

  • nionic_steps (int) – Number of consecutive ionic steps with the maximum number of electronic steps being reached before considered an error. (default: 10)


Checks if the final drift exceeds the force convergence criterion defined by EDIFFG tag and restarts if true. (See also DriftErrorHandler)

Handler Settings:

  • max_drift (float) – Defines the maximal acceptable drift. If set to None the value is set to the supplied value defined by EDIFFG in the INCAR parameters. (default: None)
  • to_average (int) – Demand at least that many steps to calculate the average drift (default: 3)
  • enaug_multiply (int) – Value used to multiply the value of ENAUG found from the INCAR parameters when restarting the calculation (default: 2)


Write a STOPCAR to the calculation folder if the calculation’s runtime approaches the defined wall time. (See also WalltimeHandler)

Handler Settings:

  • wall_time (int) – Total wall time of the job in seconds. (If running using the PBS scheduler this value is retrieved from the PBS_WALLTIME environment variable if not set here) (default: None)
  • buffer_time (int) – Buffer time in seconds between writing the STOPCAR and the total wall time is reached. Note that if the average time required to complete 3 ionic steps is larger the set buffer_time this value will be used as buffer_time. (default: 300)
  • electronic_step_stop (bool) – If set to True compare the defined buffer_time to the time required to complete electronic steps rather than ionic steps. (default: False)


Handler checking for common errors only written to stderr. (See also StdErrHandler)

Handler Settings:

  • This handler does not provide any custom settings


Corrects for aliasing (small wrap around) errors encountered for insufficient FFT grids. (See also AliasingErrorHandler)

Handler Settings:

  • This handler does not provide any custom settings


Check for both ionic and electronic convergence and restart the job with different strategies if convergence was not reached. (See also UnconvergedErrorHandler)

Handler Settings:

  • This handler does not provide any custom settings


Check for a positive absolute energy at the end of a calculation and restart with ALGO=Normal (Stops calculation is ALGO is already set to Normal). (See also PositiveEnergyErrorHandler)

Handler Settings:

  • This handler does not provide any custom settings


Check for symmetry errors and switch off symmetry (i.e. set ISYM=0) if reciprocal lattices and kpoint lattices belong to different classes of lattices. (See also MeshSymmetryErrorHandler)

Handler Settings:

  • This handler does not provide any custom settings


Checks for LRF_COMMUTATOR errors corrects the error by switching to finite-differences when calculating the cell-periodic derivative or orbitals (i.e. sets LPEAD=True). (See also LrfCommutatorErrorHandler)

Handler Settings:

  • This handler does not provide any custom settings