The upgrade experience

Hi fellow community members,

I like many others try to balance the desire to more forward quickly with leading edge release’s of OH and retain the stability required for a smart home application that controls so many aspects of my families life.

When that balance goes wrong there is hell to pay in my house :frowning:

After the v2.2 upgarde to v2.3 I found it took a couple of goes to successfully move to the newer version and stay there without rolling back.

I have just upgraded from v2.3 to v2.4 and after a couple of hours of trying to get things stable and working I have had to roll back once again.

Now, I have an initial idea of where my issues are from the upgrade experience, so now I will need to keep an eye on the forum for others that kindly provide help for those with similar issues so that when I try to upgrade again in a couple of days. I may manage to stay there.

There were a number of big changes in this upgrade that break things, and its to this, that I write this post. Not because we should never stretch the boundary and progress, but more about how do we improve, how do we do this better?

When I upgrade and I am watching my tail log and seeing many issues fly past. It is easy to get overwhelmed and trying at this time to read a number of document sources such as release notes, OH documentation set, blogs and forum posts, when struggling to understand what is going wrong often in multiple areas is stressful!!!

So to improve this experience and thinking what would make this easier I am wondering if an upgrade category could be introduced to the forum.
The new category could have add-on or issue related threads so users could look through for detailed practical information.
The release notes offer a window into a change but not in enough detail to understand how to perform needed changes or workarounds to avoid the breaks.

I love this application and try my best to contribute, just wondering if we as a community could help each other a little better with a small category change, what do you think?




It’s an idea than can be considered.
In the mean time please use the installation category

I like the idea. It can be a good place for discussions about the milestones and such.

:+1 We appreciate it!

Unfortunately I don’t foresee the upgrade process for any system as complex as OH ever becoming a super smooth process. Following the milestone builds will help some as there won’t be as many changes to deal with between versions. But it will always be a challenge for some users of some bindings. I’ve given it some thought and haven’t come up with a good solution to the problem yet.

Have you opened any threads on the problems you’ve encountered during the upgrade yet?

I do understand that the experience of such an upgrade is something that should be avoided. However with users that jump on every update without reading AND understanding the release notes that would be an impossible task.
Take the new MQTT binding as an example.
It is noted as a new openHAB2 binding in the release notes. Users of the old version 1 binding should know that the setup of would be totally different.
Why would I try such an upgrade without even thinking about the implications? That is even more true for those users that rely on MQTT for an uncountable number of devices! To make it even worse, they blame the creators of the upgrade and by that criticizing the volunteer that created the new binding! That I can’t stand!! I do feel sorry for him, having to tell such users that the solution of their “problem” is to roll back to the old binding (which they should have known beforehand!).
I do compare such an upgrade with buying a new car. Normally you buy a new one, you might read the handbook for the new features, or not. You will be able to drive the car. But now you are going to buy a car that is solely driven by an electiric-motor, wouldn’t you start thinking about how that will work for you BEFORE you even buy such a car? I bet you would!

True but… as a user I would be very surprised and somewhat annoyed if the old MQTT 1 binding were just replaced during the upgrade with no obvious way to get it back. IMHO the way this happened was needlessly disruptive and should have been handled better. I think a lot of the anger came from user’s being surprised rather than the actual change. It was not at all clear from the release notes nor the blog posting that this was going to happen. It doesn’t appear in the “Breaking Changes” section of the release notes.

In this particular case, the average user did not have all the necessary information to know and understand the implications of the upgrade even if they had fully read all the release notes. It isn’t until they upgrade and MQTT is completely broken that they find out.


Rich echo’s my position on this particular upgrade item perfectly.

I have just restarted the upgraded VM having rolled back as it was way too much to take in while things were not functioning.
I had a very simply one liner answer from David that put me on the right track that was not in the release notes or the blog (or I missed it) and that sorted me out great.

I saw mention somewhere about hue changes so I am off to see if I am ok in that regards.

I think we will never get it totally painless but we can help users find the answers quicker.

I currently have a process for upgrades that goes like this.

  1. Read release notes (pay particular attention to break changes section).
  2. Watch forums for issues for 24 hours at least.
  3. Arrange maintenance window with family
  4. Backup system
  5. upgrade all OS updates and NOT OpenHAB.
  6. Reboot system and check recovery of OpenHAB through tail log and basic UI.
  7. When happy existing system is working from a cold start I upgrade OH.
  8. tail log and look for new errors.
  9. I spend no more than two hours trying to fix issues before a roll back is declared. I grab logs prior to power off of the current system so I can work through main issues.
  10. run up the old OH system and advise the family that the upgrade will be done again after I have looked at the main issues.

so far this has got me through, the main issue I found was item 2. as there was not one place to go to in the forums but everywhere and insome cases extremely long threads to wade through take the amazing AmazonEchoControl binding that has a single thread support approach of something like 1350 posts.

anyway its all about trying to find ways to improve which hopefully we can all agree is a worthy objective.




I might recommend a slightly different set of steps which will free you to work on the upgrade incrementally rather than needing to get it all working in two hours.

Install the upgrade using the manual procedures instead of through apt. This will give you two working copies of OH to work with. Transfer your configs over to the new OH:

  • /etc/openhab2 -> /opt/openhab2/conf
  • /var/lib/openhab2 -> /opt/openhab2/userdata

You may need/want to delete the cache and temp folders from /opt/openhab2/userdata before the next steps.

Now stop OH using sudo systemctl stop openhab2.

Now start the manually install OH using /opt/openhab2/bin/ (I think, I’m going from memory, there will be a start somewhere.

Do your watching for errors and such, exercise the system and so on. If you can’t get it working in the time you have, simply stop OH (ctrl-c in the terminal where you ran and restart the installed OH using sudo systemctl start openhab2.

This way you don’t have to throw away your work you’ve done to this point and can pick right up where you left off.

Once you get the upgrade to work, you know what changes you have to make to your production OH after upgrading using apt.


Thats awesome.
I think I keep everything else and will adapt to use your suggestion on the next major upgrade (or milestone).
Thats of course if I can locate this great post when the time comes.

Thanks Rich


1 Like

I did use a second raspberry, installed the new version and tested the new mqtt binding by switching device by device to the test system. That way not the whole house would be affected if something doesn’t work.

Having a staging model is not always easy for everyone to achieve.
It could well be worth investing some time for the guiding members to provide a best practise upgrade process that does not require additional hardware or the like. such as described by Rich. In addition as a result this ‘Best Practise’ upgrade will be smoother for upgrades because it will be tested and specific instructions provided in the release notes for any changes that were needed when following the upgrade process.

That could be a reasonable step forward.



Don’t get me wrong. Yes such a best practice will be good to have and the way the new MQTT binding was introduced was less then optimal.
My point is that users that don’t read the actual documentation will not read such a best practise.

And count me in for creating such.

How do we move this from discussion to action?

My upgrade experience isn’t pretty from one version to another version especially im a binding developer. Things break as always since underlying smarthome framework changes.