Troubleshooting

Something isn't working quite right. Where do you start?

Console Messages

When you run a simulation in GridLAB-D™, after you execute

gridlabd my_model_name.glm

various messages will be written to console as the simulation proceeds, allowing you to monitor your simulation's progress and see if there are any problems with the model. Let's break down how to read and interpret those messages.

Message Severity

Messages are categorized based on how severe or important they are to your simulation. There are three categories:

  • Warning messages: WARNING[timestamp]: exec message
    • Simulation can continue, but model assumptions may be violated or defaults may be substituted.
  • Error messages: ERROR[timestamp]: exec message
    • Simulation usually cannot proceed correctly; fix these first.
  • Critical messages: CRITICAL[timestamp]: exec message
    • Unrecoverable failure in setup or execution path.

Message Phase

The timing of a message's occurance is categorized by its phase in the simulation. There are three simulation phases:

  • Loader messages: file.glm(line): load message
  • Compiler messages: file.glm(line): cpp message or file.cpp(line): cpp message
  • Simulator runtime messages: ERROR[timestamp]: exec message

Message Anatomy

Most messages include one or more of the following:

  • Source location (file and line), which identifies where parsing failed.
  • Object context (name/id/class), which identifies which model element failed.
  • Method context (e.g., climate::init, csv_reader::open), which indicates whether failure happened during load, init, or sync.
  • Timestamp context for runtime messages, which indicates when the state became invalid.

When triaging, always preserve the first error in the sequence. Later errors are often secondary effects.

Practical Triage Workflow

  1. Classify the phase of failure: Load/compile vs runtime.
  2. Capture the first fatal message: Include full line text and nearby messages.
  3. Identify object and module: Use object name, class, and method prefix from the message.
  4. Check required object relationships: Parent-child links, referenced objects, and required helper objects.
  5. Validate ranges and units: Many modules enforce bounds and will throw errors or warnings when outside valid ranges.
  6. Re-run after one fix at a time: Avoid introducing multiple changes before retesting.

Built-In TROUBLESHOOT Guidance

A large portion of the GridLAB-D™ source code includes TROUBLESHOOT comment blocks adjacent to exceptions and error paths. These are often the most direct explanation of:

  • What condition failed,
  • Why it failed, and
  • What input or model setting to change.

If a console message is unclear, search the codebase for the exact message text and read the surrounding TROUBLESHOOT block.

Common Failure Patterns

Here we detail a few common failure points and their corresponding quick fixes.

Climate and Weather Inputs

Frequent problems include missing weather files, malformed headers, unsupported timestamps, and invalid location values.

Checklist:

  • Verify file path and extension.
  • For CSV mode, ensure a csv_reader object is defined and referenced.
  • Confirm CSV headers map to published weather property names.
  • Confirm latitude is in [-90,90] and longitude is in [-180,180].

Residential End-Use Attachment

Many residential loads require a parent object that exports attach_enduse. If parent linkage is invalid, voltage response cannot be modeled correctly.

Checklist:

  • Confirm parent class supports end-use attachment.
  • Confirm connection assumptions (120 V vs 240 V) are consistent with object settings.
  • Investigate warnings about out-of-range voltage factors before continuing long simulations.

Parameter Bounds and Mode Constraints

Some objects enforce strict parameter ranges and mode preconditions during initialization.

Checklist:

  • Review object documentation for min/max values.
  • For control/experimental modes, confirm all companion parameters are set.
  • Treat warnings about "experimental" features as a cue to validate results carefully.

Use this as a quick reference mapping of common messages to likely cause and immediate action or first checks.

Table 1: Quick Reference Table
Message fragment Module Object Likely cause First checks
weather file ... access failed climate climate File path or file permissions issue Verify path spelling, working directory, and file read permissions.
no csv_reader specified for tmyfile climate climate Climate .csv input configured without a reader object Define a csv_reader object and set climate reader to that object.
column header read failure climate csv_reader CSV headers malformed or not aligned with weather properties Check header commas, whitespace, and property names against weather object fields.
unable to read time string climate csv_reader CSV timestamp format does not match expected parser patterns Normalize timestamp format and verify timefmt/input consistency.
Latitude is outside +/-90 or Longitude is outside +/-180 climate climate Geographic metadata out of valid range Correct location values and units in weather source.
parent ... does not export attach_enduse residential residential_enduse (and derived classes) Residential end-use attached to an invalid parent class Re-parent to a compatible residential object that supports end-use attachment.
Value of duty cycle is set to a value outside of 0-1 residential ZIPload Invalid cyclic-mode parameter in ZIP-style models Set duty_cycle to [0,1] (or disabling sentinel where supported).
Period is less than or equal to zero residential ZIPload Invalid cycle period Set period to a positive value.
Phase is not between zero and one residential ZIPload Invalid normalized phase Set phase to [0,1].
unable to publish properties in ... any module class-specific (varies) Module/class registration failure during startup Confirm build integrity and module compatibility with your GridLAB-D™ version.
... did not get 17 values ... (TMY reader) climate climate (TMY reader path) Weather row width mismatch or malformed TMY input Validate TMY file format and delimiter consistency.
unable to resolve localtime climate (common in climate sync) climate Time conversion failed at runtime Check simulation timezone/time settings and timestamp validity.

What to Include in a Good Bug Report

If you can't make sense of the error messages or can't figure out how to resolve the issue, you have a couple of options:

  • Visit the GridLAB-D™ Discussions forum to see whether someone else has posted about your issue or make a new post describing the issue.
  • File an issue in Github if you think the problem is in the GridLAB-D™ source code.

If you need help from maintainers or other users, when making a bug report, be sure to include:

  • The full first error message and 10-20 lines around it.
  • GridLAB-D™ version/branch
  • Minimal GLM that reproduces the issue.
  • Input files referenced by that GLM.
  • Whether issue appears at load, init, or runtime timestamp.

Reference Pages

Each module and most of their objects have a reference page in the modeling section. This is a great place to start if you have some idea of which module or object type is causing trouble in your model.

Source Code

The final authority and source of truth documentation for all things GridLAB-D™ is the source code itself. The latest version and exact relationships that comprise GridLAB-D™ are all contained in the codebase. For example, for more detail on the house object than what is contained in its documentation page, take a look at its source code.