Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 36 ยท Debugging and Testing

Error Handling and Error Clusters

Master LabVIEW error handling: the error cluster (status, code, source), error wires and dataflow, Simple and General Error Handler, custom error codes, merging errors, and cleanup.

Robust programs plan for failure: a cable is unplugged, a file is locked, an instrument stays silent. LabVIEW has a standard mechanism for this, the error cluster, and nearly every I/O VI has an error in input and error out output. Using it consistently gives you dataflow-ordered, self-reporting code.

LabVIEW is not available on this site, so this lesson describes the diagram steps and uses a Python stand-in that models the cluster and the handler.

The error cluster

It has three elements:

Element Type Meaning
status Boolean True means error, False means OK (or a warning if the code is not zero)
code I32 Numeric error code; 0 means no error
source String Where it happened, usually the VI call chain

Convention: a positive code with status False is a warning; any code with status True is an error. National Instruments reserves most code ranges for its own products. The ranges meant for your own errors are 5000 to 9999, -8999 to -8000, and 500,000 to 599,999.

How a wire runs through a VI

Wire the error cluster from the first VI to the last, left to right. Two things follow:

  1. Order: each VI waits for the error input, so the chain defines the order of execution (no sequence structure needed).
  2. Skipping: a well-written VI does nothing when error in.status is True and passes the error through unchanged. Typical I/O VIs behave this way, so a failure early on skips all later work and the final handler sees the original error rather than a cascade of consequences.

The exception is cleanup VIs (Close, Release, Clear Task): they still release resources when an error comes in but keep the first error in the output.

flowchart LR
    A["Open File"] --> B["Write"] --> C["Close File"] --> D["Simple Error Handler"]
    A -. "error" .-> B
    B -. "error" .-> C
    C -. "error" .-> D

If Write fails, Close still closes the file; the handler reports the Write error.

Handling errors: the handlers

On Dialog & User Interface you find:

  • Simple Error Handler: shows a dialog (type: OK button or continue/stop) with the code, source and explanation. Good for one-off programs.
  • General Error Handler: same plus options to add your own code list and customise the message.
  • Clear Errors: set the cluster to no-error when you expect an error (for example a timeout in a loop).
  • Error Cluster From Error Code: builds a cluster from a number, so you can generate your own.
  • Merge Errors: combines several error wires, keeping the first error found, top to bottom.

Place one handler at the end of every wire chain, and a handler inside a loop when you must react each iteration. A top-level Simple Error Handler in a deployed application with no operator to click OK will block, so log instead (see below).

Custom error codes

Choose a block of codes outside LabVIEW's, define them in a .txt error-code file with the line format code, description, and place it in <LabVIEW>/user.lib/errors. The General Error Handler then displays your messages. To raise one:

  1. Use Error Cluster From Error Code with your code and a source string, or
  2. Build the cluster with Bundle By Name and set status to True.

Use meaningful names in source (the module and the operation) since this is what the user and you will read at 2 a.m.

Return values or errors?

Use the error cluster for unexpected conditions that stop normal operation. For expected results ("no more data", "value out of range, retry") return a status in the normal outputs. Do not clear errors silently; if you must, log them first.

A model in Python

The stand-in below carries an error tuple through three steps. Steps skip if an error is present; the cleanup step always runs but preserves the first error; the merge function keeps the first error.

Python An error wire (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Logging instead of dialogs

Unattended applications should write errors to a log file with a timestamp, code and source, show a non-blocking status string on the front panel, and move to a safe state. A simple approach is an Error Logger subVI in the error path: it appends a line, then passes the error on. Combine it with the state machine so the Error Handler state decides whether to retry, stop, or continue.

Python Error codes and warnings

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Practical rules

  • Every subVI with I/O gets error in and error out (bottom corners of the connector pane, the standard pattern).
  • Never leave the error wire unconnected; at least terminate it in a handler.
  • Put close/release VIs after the last use and wire the error in so they run at the right time.
  • Generate errors from your own validations, for example a negative sample count.
  • Use Merge Errors when parallel branches rejoin.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does status = True in an error cluster mean?

    True indicates an error; a nonzero code with False is a warning.
  2. 2. What should a typical I/O VI do when error in has status True?

    Skipping and passing through keeps the original error visible.
  3. 3. Which VI combines errors from parallel branches, keeping the first one?

    Merge Errors returns the first error among its inputs.
  4. 4. Why should unattended applications avoid a dialog in the error handler?

    Log the error and go to a safe state instead.

Summary

  • The error cluster (status, code, source) travels on a wire through every VI and orders execution.
  • VIs skip work on incoming errors; cleanup VIs still run.
  • Use Simple/General Error Handler, Merge Errors and Clear Errors, and define custom codes for your own failures.
  • Log and go to a safe state in unattended programs.

Next: Unit Testing and the VI Analyzer