Technical: Troubleshooting - 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:

🔹 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're running an outdated version, update first and see if your issue is resolved before proceeding.

[!TIP] KidsChores includes built-in backup and restore capabilities. Before troubleshooting complex issues, you may want to create a manual backup or familiarize yourself with the restore options. See the Backup and Restore Guide for details.

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:

  1. Go to Settings → Devices & Services → Integrations.
  2. Find KidsChores and click on it.
  3. Select Enable Debug Logging.
  4. Perform the action that is failing so that the logs capture relevant details.

📸 Example Screenshot:

🔹 Retrieve Logs from Home Assistant

  1. Go to Settings → System → Logs.
  2. Click the three dots (⋮) in the top right and select Show Raw Logs.
  3. Look for errors related to kidschores or automation failures at the bottom of the log.
  4. 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

  1. Go to Developer Tools → States.
  2. Search for chore-related entities (e.g., _brush_teeth to find all entities related to that chore).
  3. Check that values are updating correctly and displaying expected statuses.
  4. 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.
  5. 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"
Check Pending Approvals Look at sensor.kidname_kidschores_ui_dashboard_helper → pending_approvals attribute Should show the chore with approve/disapprove button entity IDs
Approve/Disapprove Press button.kidname_kidschores_approve_chore_brush_teeth or button.kidname_kidschores_disapprove_chore_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 removed from Pending Approvals Look at sensor.kidname_kidschores_ui_dashboard_helper → pending_approvals attribute Chore should no longer appear in the list

📸 Example Screenshot: image

5️⃣ If Requested, Download Diagnostics or Access the KidsChores Data File

🚨 Privacy Note:

  • The diagnostics file and storage data contain all KidsChores data, including kid names, chore details, rewards, achievements, penalties, challenges, and badges.
  • These files do not contain Home Assistant credentials, API keys, or other sensitive system information.
  • You can share the full file as is, or find and replace any sensitive information (such as kid names) before sharing.

🔹 Easiest Method: Download Diagnostics

The simplest way to get diagnostic information is through the integration's built-in diagnostics feature:

  1. Go to Settings → Devices & Services → Integrations.
  2. Find KidsChores and click on it.
  3. Click the three dots (⋮) menu.
  4. Select Download diagnostics.
  5. A JSON file will be downloaded containing all your KidsChores data in an organized format.

This diagnostics file contains everything the integration stores, including:

  • All kids and their point balances
  • All chores, rewards, achievements, challenges, badges, and penalties
  • Current statuses, assignments, and schedules
  • System configuration settings

🔹 Alternative: Direct File Access

If you need to manually access the storage file, the KidsChores Integration stores its data in:

/config/.storage/kidschores_data

This file contains all stored information, including chore statuses, assignments, rewards, achievements, penalties, challenges, and badges.

Option A: Using the VS Code Add-on

  1. Install "Home Assistant VS Code" from Settings → Add-ons → Add-on Store.
  2. Open VS Code and navigate to: /config/.storage/kidschores_data
  3. Open and review the file. Copy the text and share as requested.

📸 Example Screenshot: image

Option B: Using the Samba Share Add-on

  1. Install "Samba Share" from Settings → Add-ons → Add-on Store.
  2. Open File Explorer (Windows) or Finder (Mac) and connect using:
    • Windows: \\homeassistant\config\.storage\
    • Mac: smb://homeassistant/config/.storage/
  3. Locate and open kidschores_data for 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! 👍