Troubleshooting: KidsChores Troubleshooting Guide - ad-ha/kidschores-ha GitHub Wiki
🛠 KidsChores Troubleshooting Guide
Why Thorough Troubleshooting Matters
Providing detailed information when troubleshooting an issue is essential. A structured approach not only helps you identify the root cause faster, but it also allows others supporting this project to diagnose and assist more efficiently. Since KidsChores is a community-driven effort, minimizing unnecessary back-and-forth by including relevant details in your initial request helps respect everyone’s time and leads to quicker resolutions.
The following steps will guide you through diagnosing and reporting issues effectively.
1️⃣ Check for Known Issues Before Troubleshooting
Before diving into troubleshooting, review existing resources to see if your issue is already documented or actively being worked on.
🔹 Home Assistant Community Forum:
- Integration Thread: KidsChores Integration Discussion
- Auto Populating Dashboard Thread: (If you are using) KidsChores Dashboard
🔹 GitHub Repositories:
- Read the latest README documentation for KidsChores and Dashboard.
- Check the GitHub Issues page of each for known problems or ongoing fixes.
📌 If your issue is already listed, avoid duplicate reports and consider adding more details or upvoting an issue instead of creating a new one.
2️⃣ Confirm You Are on the Latest Version
🔹 Integration Update:
- Go to HACS → Integrations and check for an update to KidsChores.
🔹 Dashboard Update:
- If you are using the auto-populating UI, check for updates in the Dashboard Repository.
If you're running an outdated version, update first and see if your issue is resolved before proceeding.
3️⃣ Check Your Logs for Errors
If something isn’t working as expected, logs can provide valuable clues.
🔹 Enable Debug Logging for KidsChores
Before checking logs, enable debug logging for the integration:
- Go to Settings → Devices & Services → Integrations.
- Find KidsChores and click on it.
- Select Enable Debug Logging.
- Perform the action that is failing so that the logs capture relevant details.
📸 Example Screenshot:
🔹 Retrieve Logs from Home Assistant
- Go to Settings → System → Logs.
- Click the three dots (⋮) in the top right and select Show Raw Logs.
- Look for errors related to
kidschoresor automation failures at the bottom of the log. - Copy and paste all the related log entries when reporting an issue.
4️⃣ Use Developer Tools → States to Determine if It's an Integration or Dashboard Issue
The quickest way to determine whether an issue is with the integration or the Dashboard UI is to use Developer Tools → States to find the entities directly, perform all actions, and directly observe the sensor behavior.
🔹 How to Check the Integration State
- Go to Developer Tools → States.
- Search for chore-related entities (e.g.,
_brush_teethto find all entities related to that chore). - Check that values are updating correctly and displaying expected statuses.
- If the buttons and states are working correctly in Developer Tools, then integration is likely working, and it could be an issue with the dashboard.
- If the data is missing or incorrect, the issue is likely with the integration itself.
🔹 Manual Test Flow Without the Dashboard
As an example, you can manually test chore actions using Developer Tools:
| Step | Action | Expected Outcome |
|---|---|---|
| Check initial status | Look at sensor.kidname_kidschores_chore_status_brush_teeth |
Should show "pending" |
| Claim the chore | Press button.kidname_kidschores_chore_claim_brush_teeth |
The state of the button will update to current time |
| **Confirm the claim in the Chore Status | sensor.kidname_kidschores_chore_status_brush_teeth |
Status should change to "claimed" |
| **Confirm the claim in the Pending Approvals | 'sensor.global_kidschores_chore_pending_approvals' | This drives the approval buttons in the dashboard |
| Approve/Disapprove | Press button.kidname_kidschores_chore_approval_brush_teeth or button.kidname_kidschores_chore_disapproval_brush_teeth |
|
| **Confirm the approval in the Chore Status | sensor.kidname_kidschores_chore_status_brush_teeth |
Status should change to "approved" or revert to "pending" |
| **Confirm the claim was removed from Pending Approvals | 'sensor.global_kidschores_chore_pending_approvals' | This drives the approval buttons in the dashboard |
📸 Example Screenshot:
5️⃣ If requested from the developer, Access the KidsChores Data File
The KidsChores Integration stores its data in:
/config/.storage/kidschores_data
This file contains all stored information, including chore statuses, assignments, rewards, achievements, and penalties.
🚨 Privacy Note:
- The file does not contain sensitive personal data beyond kid names and chore details.
- You can share either the full file as is, or if you are not comfortable, find and replace sensitive information like kidname.
🔹 How to Access the File
1️⃣ Using the VS Code Add-on
- Install "Home Assistant VS Code" from Settings → Add-ons → Add-on Store.
- Open VS Code and navigate to:
/config/.storage/kidschores_data - Open and review the file. Copy text and place in appropriate location.
📸 Example Screenshot:
2️⃣ Using the Samba Share Add-on
- Install "Samba Share" from Settings → Add-ons → Add-on Store.
- Open File Explorer (Windows) or Finder (Mac) and connect using:
- Windows:
\\homeassistant\config\.storage\ - Mac:
smb://homeassistant/config/.storage/
- Locate and open
kidschores_datafor troubleshooting.
6️⃣ Check for Common Causes of Errors
| Issue | Potential Causes & Fixes |
|---|---|
| Dashboard UI not updating | Try a hard refresh (Ctrl + Shift + R). If using the HA app, force close and reopen. |
| Chores not marking as overdue | Ensure valid due dates are set and chores apply to the correct days. |
str or other errors in logs |
Check for challenges missing start/end dates—this is a known cause of system-wide failures. |
| Incorrect point balances | Verify the relevant sensors and attributes in Developer Tools. |
7️⃣ Gather Details & Report the Issue
If you've gone through the troubleshooting steps and still have an issue, include as much detail as possible when reporting:
✔ Describe the problem clearly – What were you expecting vs. what actually happened?
✔ List any error messages (from logs or UI).
✔ Mention relevant entities – e.g., sensor.payton_kidschores_chore_status_make_bed.
✔ Explain any recent changes – Did you update the integration? Modify a template?
✔ Include screenshots or copies of logs/data files when possible.
Final Thoughts - Help Us Help You
Providing thorough information not only helps you diagnose your own issue, but also helps the community assist more efficiently. Since this project is developed and supported by volunteers, giving clear, structured reports allows us to spend more time improving KidsChores and less time asking for missing details.
Thank you for helping improve KidsChores! 👍