How to file an Issue

There will be times when you discover a bug in OH. This tutorial explains how to file an issue so the developers can know about the bug and hopefully fix it.

Do I Have a Bug?

openHAB is a complex system with lots of options and ways to configure various capabilities. As the old saying goes, openHAB gives you a lot of rope with which to hang yourself.

So how do I as an average user know whether I’ve done something wrong or if there is a bug? The good news is we don’t expect you.

Step 1: Ask for Help

If you are having a problem, please open a new topic here on the forum. Try to pick the category that makes the most sense to you but don’t worry if you get it wrong. We can move it if we need to. But choosing the right category increases the likelihood that the right people will see and help.

There are a group of forum users who scan pretty much every new posting. These users are usually not developers but long time users of OH, or newer users who are looking to contribute back to the community. These users will ask lots of questions and have you try experiments to help narrow down the source of the problem.

But, there are lots of posts and very few of these tier one helpers. So please review How to ask a good question / Help Us Help You. Respect the time these users are donating by providing as much detail as possible.

Step 2: You Have a Bug

The tier one folks have determined you have a bug. If they have they will ask you to please file an issue.

Why do I have to file the issue? Well, you are the one with the problem. The tier one folks are not experiencing the same problem as you; they may not even be using the same binding or similar setting. Often the developers will need more information from you than has already been provided in order to reproduce the problem and hopefully solve it. Thus the user(s) who are actually experiencing the problem must be the ones to file the issue.

Filing an Issue

Step 3: Where to File an Issue

All of the openHAB repositories are hosted on Github under There are lots of repositories there and it’s not always obvious which one is the correct one. Luckily, the tier one folks from above will tell you the proper repository to file the issue in. Usually we will provide a link but if we don’t browse through the list until you find the repo mentioned.

Step 4: Create an Account

To file an issue you must create a GitHub account. An account is free and easy to set up. You can have an account in just a couple minutes.

Step 5: Search for Similar Issues

There may already be an issue opened for this problem. The tier one folks often are not able to follow all the issues as they get created so may not be aware if an issue already exists. If you find a similar issue, please add a comment indicating you have the same issue and provide a link to the forum thread and any additional details you think might be relevant.

Step 6: Create an Issue

If you didn’t find an issue that seems to apply, create a new issue.

The text entry for the new issue will come pre-filled with text asking for all the information needed in the issue. Please provide all the requested information. Also provide a link to the forum thread.

Once created, return to the original thread and post a link to the Issue you just created. Others who are experiencing the same problem will be able to follow the Issue as it get’s worked and contribute other information that might be critical to solving the problem.

Step 7: Help Solve the Problem

The developers will likely need additional information to diagnose and solve the source of the problem. Please answer any questions asked and provide any artifacts requested.

Now What?

Hopefully a developer will start working and help solve the problem. However, sometimes the developer may be offline for extended periods. Sometimes there isn’t a developer willing to work on the issue. Sometimes there are higher priorities among the developers.

We cannot promise that the issue you discovered will get fixed nor how quickly it will be fixed. Some get fixed within hours of being reported. Others have been open for years. Please be patient and understanding. Like the tier one folks, all of the developers are also donating their time to this project.

I Can Fix It Myself!

Fantastic! If you are talking about code then you probably already know how to manage submitting a PR so this section will focus on updates to the docs which anyone can do.

Even if you plan on filing it yourself, it is good form to open an issue to let others there is a problem. Let them know in the issue that you intend to file a PR to address it.

For simple fixes, making the update couldn’t be easier. At the bottom of each documentation page there is a link that will take you straight to the file on GitHub.


Click the edit icon.

This will create a fork of the project under your user name. Make your changes right there in the browser. At the bottom, create a title for your changes and describe your changes and why you made them. Make the last line in this comment "Signed off by " showing that you are agreeing to apply the openHAB open source license to your contributions. Then click “Propose file change”. Also add “Solves issue #XYZ” where XYZ is the issue number you created. This will automatically link this PR to that issue.

This will open a diff view showing you what you changed. If you are satisfied, click “Create pull request”.

This will submit the proposed changes to the original github repo for review before it’s merged into the baseline. There may be comments and proposed changes you need to make before it get’s approved.

Congratulations and thanks!

If you happen to have more than one issue that you want to work on, you will want to create branches, but that’s beyond the scope of this tutorial. Search and you will find GitHub has lots of great tutorials covering this.

Getting Started with OH3: rewriting the tutorial - 1. Introduction
How to create a sitemap from a Semantic Model (OH3)
Error when running openhabian-config 1.6.2 Menu #14
Discussion for "How to contribute to the openHAB Documentation"
[Wiki] How to contribute to the openHAB Documentation
Known issues on OH3 upgrade
Cron resets to 08:00 when updating in adminstration/Rules dialog
openHABian - Mosquitto MQTT failed to start
HowTo make changes / minor corrections to the documentation?
Scripts in OH3
Adding new Items from existing equipment in the model?
Items.metadata json file bug?
Migrating MQTT1 items to MQTT2.4 items
NeoHub Binding Update
Problem with update Openhabian
MQTT TLS certificate pinning - incorrect hashes
MQTT-Binding: cannot read values with | (pipe) in topic
Android App Remoteaccess
Dark Sky - Yawb4oH2 (Yet another weather binding for openHAB 2)
The ability to replace a node on a controller would be fantastic!
Ephemeris datetime parameter
[SOLVED] Openweathermap: forecastDays is to 5 but value in Things is 0
[SOLVED] Sonos room name parser for multi-language
Serious 2.5 Release issues. How to troubleshoot?
Azure IoT Hub Connector installation
[Exec Binding] Spaces in arguments (Workaround)
Webhooks - Myopenhabcloud or other method
[SOLVED] Handling and responsibilities in bug tracking
MQTT 2.5 M1+ How to implement the equivalent to MQTT1 REGEX filters
Openhabian console login fails
Astro Binding - Events scheduled but not triggered
[SOLVED] Handling and responsibilities in bug tracking
[SOLVED] OpenHAB 2.5 RC 1 Critical Issues
[SOLVED] iCloud Thing cannot be added
[SOLVED] Handling and responsibilities in bug tracking
[SOLVED] Handling and responsibilities in bug tracking
Mqtt log-warn Build #1761
MQTT 2.4.0 Binding qos is 1
[SOLVED] Total disaster when trying on my own, with the great help of this community I got it running. Thanks
AVM Fritz!DECT 200 with Logitech Harmony Hub
Rrd4j only stores one datapoint
Swiches with mapping: error in WEB-UIs (Basic+Classic)
How to solve Exec binding problems
(Bug) Android App Webview rendering issue
Chart display temperature values in exponentional format
Meteoblue Binding - Only forecast data available - missing current data
How to rollback from 2.5 Snapshot to 2.4 Stable
Rrd4j Graphs not working
Mqtt embedded broker not responding
No Item Expose to Cloud
Network Binding not finding anything
Openhabian configuration tool documentation
[SOLVED] Openhab android app sends commands after delay of 10-20 seconds
OpenHAB 2.4 MQTT beginner experience *principal conclusions* from a post-newbie
RFXCom X-10 Dimmer and missing
[SOLVED]Setpoint and MyOpenHab Cloud Connect
Discussion about OpenHAB Item types
Astro:sun:night#start channel UNDEF and others too
Problems with Amazon Echo Control Binding if internet connection lost
Astro:sun:night#start channel UNDEF and others too
Moving to MQTT 2.x
Troubleshooting CalDav Personal - Public Garbage Collection Calendar
Type Conversion / persistence issue?
InfluxDB not doing anything
Design Pattern: Time Of Day
[SOLVED] Sitemap not updating (probably because rest events api hangs)
Persistence only working for minutes
Help with documentation
Installation of Embedded MQTT Broker with 2.5.0-SNAPSHOT fails AND/OR connection refused
[ERROR] [org.apache.karaf.log.core ] - FrameworkEvent ERROR - org.apache.karaf.log.core java.lang.IllegalStateException: Configuration Admin service has been unregistered
[SOLVED] HABPanel - What am I missing?
Netatmo Outside Temp stops writing to persistence DB (influxdB) after a month
[unifi] Unifi binding feature request:
Runtime commands missing on Karaf
OpenHAB3 Start Up Issues - Race Condition? How to Sequence Startup?
How to figure out how to do something in openHAB 3
[Solved] Bug: Mysterious folder hierarchy created
OH3 Can't add a Thing' trigger channel event to a rule
Presumably identified defect in sitemap editor

Another great tutorial. Thanks!

Having read the discussion going on with 2.5RC1 and having issue with MQTT myself may I suggest an addition to the process above. After the git issue has been raised go back to any entry you may have made in the forums and update with the link to the github issue.

This may help others to see an issue has been raised and can then go directly to the reference. Also if dev’s do read the forum they will see that a git issue has been raised.

Small process update, but may help people.

I’ll add that to the instructions. That usually happens in practice but sometimes it’s missed. Thanks!