How to help us help you - or How to ask a good question

Before we begin…

This forum is not a helpdesk

The people here don’t work for Home Assistant, that’s an open source project. We are volunteering our free time to help others. Not all topics may get an answer, never mind one that helps you solve your problem.

image
This also isn’t a general home automation forum, this is a forum for Home Assistant and things related to it. Any question about Home Assistant, and about using things with Home Assistant, is welcome here. We can’t help you with everything though.


:zero: Language

We can only support one language here, and that language is English. We appreciate that not everybody can read and write it, but there are a wide range of options out there. We chose this language since it’s known to the moderators and developers, and also one of the most widely known languages.

Alternatively there are other places you can get help in other languages.

:one: Search

It’s not unlikely that your question has been asked, and answered, already. If you search the forum, you may find it and save yourself a lot of time.

Now, it may not be a perfect answer to your question, but it should get you close enough to start.

When you’re writing a new topic, on the right-hand side (where the Preview panel is), you’ll see topic suggestions. These are chosen based upon your title, tags, and the post content. Do check them before you post.

If you find a post that solves your problem, please like that post. It’ll help others identify that post as helpful, and let that poster know that they’ve helped people.

:two: How do I search?

Try to search only for what is the core of your question - the error message (without your specific data), component or add-on name, the operation you want to perform, etc.

Some examples of searches for common scenarios:

  • hassio “no such image”
  • mqtt light
  • camera stream

:three: I found a similar topic but it’s already solved and I still have a problem. Should I post in it?

As a rule of thumb - no.

What you could do, is to post your question in a new topic and put a link to the topic you found (see also 9 Show your workings below).

:four: Did you read (and search) the documentation?

The documentation is here, and the integration list is here (integrations used to be called components). There are a few highly recommended sections that everybody should read:

The documentation and the integrations also have search functions.

Be warned, Home Assistant changes quickly. If you’re looking at a post in the forum, or somebody’s blog post, or a YouTube video, and that article is months old, it could turn out to contain outdated information. If you run into problems it’s good to check against the current documentation.

Don’t forget, add-ons will have their own documentation too. In many cases it will be embedded in the add-on, or accessible through it, but if not check the add-on page or the relevant GitHub repository (for a non-core add-on).

Good questions

:five: Use a relevant category

The categories are fairly self explanatory, and Uncategorized is where things without a category fall. Please try to help them end up somewhere else :wink:

:six: Use relevant tags

Tags are added to a topic to help to improve the forum’s search engine, as well as give additional context to people reading your question.

Common tags include zwave, mqtt, templates, switch, etc.

:seven: Title

Having a good topic title is essential. It should summarise your post so that without even opening it people can have a good idea of what it’s about.

A good topic generally:

  • Includes unique part of the error you’re getting
  • Contains the integration name or action description
  • Describes the thing you’re having an issue with
  • Is emotionless

For example:

  • Good How do I use a timer in an automation to delay an action?
  • Bad Timer not working
  • Ugly Problem/Need help
  • Good Z-Wave - Not able to include device ZXX123
  • Bad ZXX123 not discovered
  • Ugly ZWave problem

If you’re having a problem writing a good topic title, leave it for last - once you’ve written the whole question, it might be easier to write a summary title for it.

Asking the question

Before posting anything make sure that you read and follow the community standards

:eight: Describe the goal, not the problem

It’s all too easy to fall into the trap of the XY problem. If you describe your goal first, then others can understand what you’re trying to achieve.

:nine: Show your workings

If you turn up with a post that suggests you’ve put in no effort, you’re less likely to get quality help, and your post may even be ignored. Explain a bit of what you’ve done so far, such as:

  • Link to some other threads that you’ve found, and tried, and explain why they didn’t help you
  • Describe what you’ve tried, and what the problems were

Showing that you’ve put effort in will help demonstrate that you’re not simply looking for others to do all the work for you.

:one::zero: Tell us how you installed Home Assistant

Tell us if you’re running Home Assistant using an official HassOS image, a Docker install, a venv install, and so on. Things that are often really useful to know include:

  • What version number of Home Assistant are you running?
  • How you installed it. If you’re not using a HassOS based install, remember to tell us the operating system
  • Any relevant code - correctly formatted

For example:

  • Home Assistant 2022.11.0 using the HassOS image
  • Home Assistant 2021.12.2 in a venv following this guide on Windows 10
  • Home Assistant 2022.2.42 on Ubuntu 22.04 following this guide

Please remember that words like latest, current, newest and so on are not version numbers.

:one::one: Format it properly

When sharing the code, share it as text and not an image. When you do that, remember that spacing is critical in YAML, and if you just throw the code on the page then it’ll look ugly and nobody will know if the problem is because of spacing. We need you to use code blocks and appropriate markup.

For example, this is easy to read and it is obvious if the spacing is correct:

# Turn off lights when everybody leaves the house
  - alias: 'Rule 2 - Away Mode'
    trigger:
      platform: state
      entity_id: group.all_devices
      to: 'not_home'
    action:
      service: light.turn_off
      entity_id: group.all_lights

This however, not so much:

Turn off lights when everybody leaves the house

  • alias: ‘Rule 2 - Away Mode’
    trigger:
    platform: state
    entity_id: group.all_devices
    to: ‘not_home’
    action:
    service: light.turn_off
    entity_id: group.all_lights

Full details are in that link, but in brief you wrap your block in three backticks (```), like this:

```
# Turn off lights when everybody leaves the house
  - alias: 'Rule 2 - Away Mode'
    trigger:
      platform: state
      entity_id: group.all_devices
      to: 'not_home'
    action:
      service: light.turn_off
      entity_id: group.all_lights
```

:one::two: Describe what you changed

If it used to work, then tell us what changed since then. If you changed an automation, upgraded something (a custom integration, an add-on, Home Assistant itself, etc), we need to know. Don’t just tell us the last change, tell us all the changes.

Remember too - only change one thing at a time, then test. If you change multiple things and it now works, you don’t know what solved it. Worse, one of those things may have solved it, but one of them may have introduced a new problem.

:one::three: Share the logs

If something isn’t working, check the logs and see if things are being logged. The Home Assistant log is available in the UI, though information on custom components only appears in the log file on disk, or you can check them using the command line - ha core logs. Keep in mind that the UI will only show errors, and other entries may be helpful and relevant. Other sources will include:

  • Home Assistant log file homeassistant.log
  • Supervisor log
  • Add-on logs

For automations and scripts make sure to include the debug trace. Downloading and sharing the trace’s .json file is an efficient way to provide us with information about how your automation is designed an what is failing.

The more you tell us, the more likely it is that the problem can be identified.

:one::four: Screenshots

Sometimes an image is worth a thousand words, and including a screenshot (or a link to one hosted elsewhere) can help. Don’t do that for anything you can copy and past from your configuration, YAML, code, or logs. Please only include screenshots that are actually helpful.

:one::five: Read before posting

Yes, read your own post before you post it. Make sure that you’ve not lost the point part way through, that it still makes sense, and that the topic, tags, and category all still make sense.

The other things to ensure is that you’re using paragraphs, punctuation and white space. A wall of text is hard to read.

:one::six: Should I tag people?

Generally, no.

It comes across as bad manners, you’re demanding somebody answers you. It’s different if you’re thanking somebody, obviously.

If you do tag somebody keep it polite and respectful. Remember that everybody is a volunteer, and nobody has to help you.

Similarly, please don’t PM (private message) people asking for help. It also comes across as demanding, and means that others can’t learn from what you do.


I’ve posted…

:one::seven: Wait…

Yes, the community covers the world, but those who can help you may not be around. It can easily take many hours, maybe even a day or so to get a response.

:one::eight: But it’s been days

If nobody has responded after a couple of days, have a re-read and see if the title, category, tags, or even the post itself need some attention. Re-read this guide and see if you’ve missed something important.

If you think that all is as good as you can make it, then you can consider bumping it by posting a reply to make it more visible. Doing that too much, or too quickly, can make you look entitled, and that will drive people away.

:one::nine: I’ve solved it!

Great. Please respond to your post with details how you solved it, and use the option to mark it as the answer (see 21 below).

Please don’t delete your question, that will make it look like you only care about yourself.

:two::zero: People are replying, but I don’t have the answer

This is common. There’s always going to be things people don’t know (because you didn’t tell them, and maybe didn’t even know to tell them, or because it’s beyond the limits of their knowledge).

If something that people have said has moved you on, then let them know. This will encourage people to keep helping you. If it hasn’t, let people know that you’ve tried their suggestion, and what happened. Again, this encourages people to keep helping you.

:two::one: Somebody’s answer solved it!

Fantastic!

Now, before you go… please take the time to mark that as the answer, you do that by selecting the three dots under the post:

image

Then select the check box:

image

Don’t forget too while you’re down there to click the heart to like the post, as a way of saying thank you.

:two::two: Be respectful

Please do read the code of conduct.

:two::three: Don’t use ChatGPT

Don’t use ChatGPT, or similar tools, to generate answers that you provide. These tools often produce results that look good but are incomplete, misleading, or just plain wrong. If we believe that you’re doing that then we may suspend your account.

:four::two: This can’t work, can it?

Try it :wink:

Remember, there’s never a guarantee you’ll get an answer - nobody is required to provide one. What you can do though is provide a post with relevant supporting information, that shows you’re trying. That will encourage people to help you.


Inspired by this awesome post over in the OpenHAB forums.

169 Likes