Skip to content

Issues

This page shows you how to report an issue for HACS.

Reporting an issue

If you're having an issue with a custom element, report an issue for that repository.

To report an issue with HACS, use one of the issue templates.

  • All templates have a defined structure. Follow the structure and provide the requested details. Issues missing required information will be closed.

What should be in the issue

The content of the issue depends on the type of issue. At least, include the following information:

  • A GOOD description of the issue.
  • Check out some real-world examples of good and bad issue descriptions.
  • Debug logs.
    • To enable debug logs for HACS, follow the steps on enabling debug logs.
    • Logs are more than just errors; debug logging provides a full picture of what happened.
  • Steps to reproduce the issue.
  • If the issue is in the UI, add screenshots.
  • Diagnostics

Warning

Issues that are missing required information will be closed.

Tip

oh... and almost forgot... latest is NOT a version. Provide the actual version number.

Issue examples

This section provides a collection of good and some bad (unhelpful) issue descriptions.

Examples of bad issues


Yes the issue was blank it only had a header 'CCH Settings'


Version of HACS
Describe the bug
A clear and concise description of what the bug is.

Debug log

Add your logs here.
The description of the issue only contained the template but it had a header 'Blows up on update.'


Version of HACS
Describe the bug
A clear and concise description of what the bug is.

Debug log

Add your logs here.
The description of the issue only contained the template but it had a header 'zod'


[Expecting value: line 1 column 1 (char 0)] Restore Failed!
11:51 AM custom_components/hacs/hacsbase/data.py (CRITICAL)
I checked and it exactly how its supposed to be
even replaced the whole hacs folder with a fresh download

Examples of good issues

Good issues have too much text to extract (some also have screenshots), but a few are linked below:

Flagging a repository for removal

This should only be used when there are grounds for removing (blacklisting) a repository in HACS.

If you don't like a repository, have issues with it, or it's not working, you should report that to the repository owner, not to HACS.

When you are flagging a repository, provide at least the following information:

  • A reason why this repository should be removed.
    • "It's not working" is not an accepted reason.
    • "It's not working and it has not been maintained for an extended period of time" could be a reason.
  • The name of the repository.
  • Proof that you have tried to contact the owner of that repository.
    • Provide a link to the issue you created in their GitHub repository.

Last words

The more time/words/examples you put into your issue, the better the chance someone else can understand what your issue is. You are more likely to get help.