Known issues on OH3 upgrade

openHAB 3 got released and you might be running into issues when or after you upgrade.

This post is meant to summarize the most often encountered problems to show up on upgrading your system to openHAB 3.0. I’ll update/extend it over time.
Let me know if you feel there’s substantial stuff missing (issues) or insufficient (explanations how to fix).
Please cross-check before opening your own thread (let alone jump on someone else’s).

First things first

The very first thing to check out is the breaking changes section of the Release Notes if your issue is a known issue and as such expected to show up. See there as well for pointers how to cope with these issues.

is it openHAB, really ?

Make yourself aware if your issue is really caused by the openHAB upgrade you went through

  • did your issue exist before the upgrade ?
  • is it that rules no longer do what they did, eventually because of bad or missing initialization of item states? I.e. is it really the openHAB code or rather your own rules to have a problem ?
  • might it rather be an issue with openHABian or the OS you run on and its setup ?


If you run on openHABian, in order to be able to analyse issues you should always

  • set (or add if missing) debugmode=maximum in /etc/openhabian.conf
  • set your terminal to record the output of your activities.

before you start openhabian-config.
This is crucial to be able a) to look up what you did and what the system’s response was and
b) to eventually open a Github issue to make developers aware of your problem and to provide them right in the first place (i.e. when you open the issue) with the information they need to help you.

openHABian branch

There are branches (= different code versions) of openHABian, too - not to be confused with the openHAB versions themselves. Think of it as the environment openHAB lives in.
You can use option 01 to change branches.
You need to use the openHAB3 branch for OH3. For OH2 you must the ‘stable’ branch. master is equal but will be deleted soon.
To successfully complete the upgrade process, openHABian needs to change you over to the openHAB3 branch. That happens automatically if you select the upgrade option 03 in openHABian. It does in most but not all cases.
Unfortunately there’s many possible starting points (many versions of openHABian on many Linuxes on various hardware) and depending on your starting point this switching to the proper environment may not have worked.
The branch you start in every time you fire up openhabian-config is defined as the clonebranch parameter in /etc/openhabian.conf and shows up in the menu title bar.
There used to exist a bug in openHABian that once you actively switched branch or the system did for you as part of the 03 OH3 install option, it didn’t store that information into clonebranch which is why you were reset to the original branch on next openhabian-config start.
There also used to be instructions how to manually install openHABian on other Linuxes that were not updated in time to reflect the openHAB 3 changes. They used to tell you to clone the stable branch. That was (and in fact still is) correct when you want to get openHAB 2 as it installs the environment for openHAB version 2. However everybody expected to get the openHAB 3 version installed (or the OH3 enabled openHABian environment). They didn’t and many subsequent actions failed because of the differences in OH2 vs. 3 such as directory names.
Eventually downgrade (menu option 42#2) or purge the openhab package and select menu 03 to install again.

If these hints do not work for you, the safest thing to do is to install openHABian again, from scratch.

Bintray shutdown

You may or may not still download addons from bintray. This no longer works as they have shutdown their service, see this post for more info.
If you have not so far, switch to use kar archive files now rather than to download the addons each time you start openHAB.
Set remote=false setting in /etc/openhab/services/addons.cfg or use the corresponding UI switch.

Broken time processing in rules

OH3 removed the Joda libraries many of us used to handle time related events in rules DSL code.
There’s Java classes available to replace them but it does not work 1:1 so you need to change some of your rules code. See links at the end for pointers.

Links for further reading


Hi Markus,
today i wanted to upgrade my OH2.5 to OH3. Unfortunately i had to roll back due to missing addons. I know that some addons may be removed due to the removal of the compatibility layer. But it seems that some more are missing. Here is what i found so far:

  • EnOcean: it is listed online (Add-ons | openHAB) but during setup it was not available (using latest docker image)
  • Fritzbox TR064: maybe its an old one but i am not sure. A list of removed addons would be helpful
  • Hue: dont know if it is renamed to Philips Hue or if they are different addons

At least a more detailed list of removed/renamed addons would be great. So users can switch to another implementation before upgrading.
In general it was a bit strange that i had to run a setup wizard and install plugins which might already available because it did an upgrade and not a clean installation. Maybe you can add this to some upgrade guide.

I added that. But it’s all publicly available knowledge.
It’s not secret withheld by some developer. A rather simple google search found it.
Yes it often requires some efforts to find, and sometimes even a lot of but anyone including yourself could have done that.

So please to all users out there:
Please don’t reply here only to ask for more information. Open your own thread.

Gather and share your knowledge not your complaints.
Contribute yourselves. Thank you.

1 Like

3 posts were split to a new topic: Looking for bindings

A post was split to a new topic: Issue with GUI defined DSL rules

2 posts were split to a new topic: Tr064 binding new name

2 posts were split to a new topic: openHABian upgrading hangs

A post was split to a new topic: Dimmer issue?

2 posts were split to a new topic: Non default port

Please guys only post here if the issue is of interest to a wide audience and impact many.

For your own issues, open your own threads please, and mind the posting rules.
I’m not your caretaker to sort your communications for you. Thank you.

How to ask a good question / Help Us Help You - Tutorials & Examples - openHAB Community

A post was split to a new topic: Habpanel issues


I noticed you split my post about using a custom port. Does this mean you won’t treat this as a general upgrade issue that impacts a wide audience?

Fine with me, but then I’m going to close the thread as I now installed from scratch anyway. Nevertheless I think that an upgrade function shouldn’t ignore such a configuration change.


Well I only have a peek at posts so can easily be mistaken when taking the decision to move a post.
A custom port in the first place IMHO is a custom problem. I don’t think many users change it.

1 Like

A post was split to a new topic: Upgrade issue

HABPanelViewer: OH3 changed REST event topics (not mentioned as breaking change), thus HABPanelViewer Command Item is broken. For now use 0.9.27pre linked in first post of HABPanelViewer thread until an official release is available.

A post was split to a new topic: OH3 persistence freeze

A post was split to a new topic: Upgrade issues with Samba et al

A post was split to a new topic: Cors problem

Hi Markus,
I noticed that in the breaking changes it’s missing the fact that this API will no longer be working. I know it’s not an official API, but many users rely on this API for their setups, so I think everyone should know it:


I have opened my own topic on the subject, as a workaround should be provided: