Troubleshooting Maximum Iteration Errors

Maximum iteration errors are among the most common warnings encountered in EnergyPlus and DesignBuilder simulations. These errors indicate that the simulation is unable to converge on a set of flow rates and temperatures that meet the current load conditions within the specified number of iterations.

What causes maximum iteration errors

Maximum iteration errors are usually related to mass flow or temperature problems around HVAC loops. For example, this can occur when the air loop side is doing something contrary to the zone equipment, creating conflicts in the HVAC system simulation. In simple terms, the simulation is trying to balance several factors:

• The airflow each zone requires
• The temperature of that airflow
• The available heating and cooling capacity
• The timing of equipment operation

When these don't align, the model gets stuck in a loop, repeatedly trying to reach a physically impossible solution.

Common causes

Below is a concise introduction to the common causes of maximum iteration errors:

• Airflow mismatches: The sum of terminal unit airflows does not equal the supply fan airflow
• Inconsistent equipment schedules: Conflicting operating schedules between related components
• Inconsistent control setpoints: Conflicting temperature or airflow control setpoints
• Undersized equipment: Coil and plant equipment capacities insufficient to meet supply air setpoints
• Complex system types: Variable Air Volume (VAV) systems with reheat or floating supply air temperatures are especially prone to these warnings.
• Controller convergence issues: Loose controller convergence tolerances

When to be concerned

The significance of maximum iteration errors depends on several factors. In general, how often the errors occur is more important than the total number reported. The total count of errors can vary greatly depending on the model’s complexity - such as the number of zones, air systems, and the length of the simulation period. For example, a thousand errors might be acceptable in a large annual model but could indicate a problem in a small, single-zone design-day simulation.

It is also important to consider when the errors occur. If they appear at every timestep, they likely indicate a persistent HVAC system issue. However, if the errors occur only occasionally, such as during periods of rapid system change like setback or recovery, they are generally less concerning.

Finally, assess how these errors affect system performance. If the zones maintain proper temperature control and the errors occur only intermittently, the results are probably not affected. On the other hand, if the zones consistently fail to meet their setpoints, the errors are significant and will impact the accuracy of the simulation.

See the Max iterations exceeded section of the Tips and Tricks for Using EnergyPlus guide.

Diagnostic steps

When convergence warnings arise, follow a structured diagnostic workflow to uncover their root causes: review the detailed error log to pinpoint struggling systems, enable extra warnings to reveal hidden conflicts, and examine key hourly outputs to trace mismatches in temperatures or flow rates.

a. Review the EnergyPlus error file

When maximum iteration errors occur, the first step is to review the EnergyPlus error file (eplusout.err). This file lists all warnings and errors generated during the simulation and is the primary source for identifying convergence issues. Always read the file from the bottom upward. The final message usually describes the most serious problem. Repeated “maximum iteration” messages indicate that certain systems are struggling to find stable operating conditions.

b. Display extra warnings

For a more detailed understanding of the problem, you can enable additional diagnostic messages in EnergyPlus. This is done by checking the Display extra warnings Program option. These extra warnings can provide valuable insights into the cause of convergence difficulties, such as mismatched setpoints or unstable controller behaviour.

c. Analyse key hourly results

It is also helpful to examine key simulation outputs to understand how the system behaves during the problem periods. Reviewing hourly results for zone air temperatures, system flow rates, and coil or loop outlet temperatures can reveal where the mismatch or instability is occurring. For instance, abrupt temperature swings or unrealistic flow rate changes often indicate issues with system control or component interaction.

If the simulation fails with a fatal error and the output results are not available (like .csv or .eso files) running shorter simulations (e.g., single design day or one-week period) allows to identify the exact day or time when instability occurs, produces results faster, helping with iterative debugging, and makes it easier to visualize system behavior in the output variables. Once the model runs stably over a short period, extending to a month or full-year simulation can be done in confidence.

Solutions and Troubleshooting

Once maximum iteration errors are identified, the next step is to focus on resolving their underlying causes. Most solutions involve refining equipment sizing, improving control logic, or adjusting simulation settings to help the model reach stable operating conditions.

a. Check Equipment Sizing

Undersized coils, fans, or plant components are among the most common reasons for convergence issues. The first step is to confirm that all HVAC equipment can meet the required loads. Whenever possible, use the autosizing feature rather than fixed capacities. Autosizing ensures that coils, fans, and controllers are proportionally sized to the building’s actual heating and cooling demands. If manual sizing is necessary, verify that coil capacities, plant loop flow rates, and fan airflows are consistent with the design intent and that supply airflow matches the sum of the terminal unit flows.

b. Review Control Logic and Setpoints

Inconsistent or conflicting control logic can cause EnergyPlus to oscillate between incompatible conditions. Check all temperature and flow setpoints for consistency across the system. Simplifying control logic and maintaining consistent setpoints between related components often eliminates persistent iteration problems.

c. Adjust Convergence Tolerances

If the system configuration appears correct but iteration errors persist, you may need to relax the simulation convergence tolerances. The temperature and loads convergence values can be found under the Advanced header on the Options tab of the Simulation Calculation Options dialog.

EnergyPlus uses two main settings to determine how closely it must match energy and temperature balances before proceeding to the next timestep:

• The temperature convergence tolerance, which defaults to 0.4°C
• The loads convergence tolerance, which defaults to 0.04.

 For complex models, slightly increasing these values can help achieve stable results without meaningfully affecting accuracy. It is best to adjust these parameters gradually while monitoring simulation stability.

Summary

Maximum iteration errors require systematic investigation focusing on HVAC system configuration, equipment sizing, and control logic. While some intermittent errors may be acceptable, persistent convergence failures indicate underlying modelling issues that can significantly impact simulation accuracy. The key is to identify whether the errors affect system performance and zone conditions, then address the root cause through proper system configuration and convergence settings.