Skip to content

openHAB Things Error

DodaTech Updated 2026-06-24 3 min read

In this tutorial, you'll learn about openhab things error. We cover key concepts, practical examples, and best practices.

Hook

You add a new thing in openHAB. It appears in the inbox, you accept it, but the status stays "OFFLINE" or "UNKNOWN." The device is powered on, reachable via ping, but openHAB cannot communicate with it.

The Wrong Way

Removing and re-adding the thing repeatedly does not change the outcome if the binding configuration is wrong.

# BAD: Removing and re-adding the same thing
openhab-cli thing remove zwave:device:controller:node1
openhab-cli thing add zwave:device:controller:node1
Thing removed
Thing added
Still OFFLINE — same config, same result

Re-adding does not fix a configuration mismatch.

The Right Way

Check the thing configuration, binding status, and logs to find the real problem.

# 1. Check the binding status
openhab-cli info | grep -i binding
ZWave Binding: INSTALLED
MQTT Binding: NOT INSTALLED
# 2. Check the thing's configuration in the UI
# Settings → Things → Select thing → Code tab
{
  "thingTypeUID": "mqtt:topic",
  "label": "Temperature Sensor",
  "configuration": {
    "broker": "mqtt:broker:mybroker",
    "topic": "sensor/temperature"
  }
}

The broker reference mqtt:broker:mybroker may not exist.

# 3. Check openHAB logs
tail -100 /var/log/openhab/openhab.log | grep -i "thing\|error\|offline"
2026-06-24 10:00:00.000 [ERROR] [thing.mqtt.topic] - Failed to subscribe to topic sensor/temperature: Not connected to broker
# 4. Fix the MQTT broker thing first
# Settings → Things → MQTT Broker → Edit → Check host/port/credentials
# 5. After fixing the broker, things linked to it come ONLINE automatically

If the binding is properly configured but the thing stays OFFLINE, the device may require a specific initialization sequence:

openhab-cli thing set-status zwave:device:controller:node1 ONLINE

Prevention

  • Configure bridge things (broker, USB gateway) before the child things that depend on them.
  • Check openhab-cli info for binding installation status.
  • Monitor openhab.log during thing initialization.
  • Use the Main UI's thing code view to verify all configuration parameters.
  • Follow the specific binding's documentation for minimum configuration requirements.

Common Mistakes with things error

  1. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
  2. Using return to exit a function early instead of wrapping a pure value in the monad
  3. Mixing let bindings with <- bindings in do notation, producing type errors

These mistakes appear frequently in real-world OPENHAB code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

What is the difference between a thing and an item?

A thing is the physical or virtual device (a Philips Hue bulb, an MQTT topic). An item represents a property of a thing (brightness, switch state). Things bridge between the physical world and openHAB items.

Why does my thing show UNKNOWN instead of OFFLINE?

UNKNOWN means the binding cannot determine the thing's status. This often happens with network devices that did not respond to the initial handshake but may work for commands. Try sending a command to the thing.

Can a thing be ONLINE but its items show NULL?

Yes — the thing can be connected but its linked channels are not reporting values. Check the channel configuration and the device's publishing interval. Some battery-powered sensors may need waking up.


DodaTech — openHAB things that stay connected.

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro