Technical: Troubleshooting

Why Thorough Troubleshooting Matters

Providing detailed information when troubleshooting an issue is essential. A structured approach helps you identify the root cause faster and helps maintainers assist more efficiently. Since ChoreOps is community-driven, sharing relevant details in your first report reduces back-and-forth 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:

• If needed, use the forum search for current ChoreOps discussions and troubleshooting posts.

🔹 GitHub Repository:

• Read the latest README documentation for ChoreOps.
• Check the GitHub Issues page 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 ChoreOps.

🔹 Dashboard Generator & Templates Update:

• The dashboard generator and templates are part of the main ChoreOps repository.
• Updating ChoreOps updates both integration behavior and dashboard template logic.

🔹 Dashboard Dependency Update:

• If the issue affects dashboards, generated views, or custom cards, update dashboard dependencies such as button-card to the newest available version as well.
• In HACS, review Frontend and update any ChoreOps-related dashboard dependencies before continuing.
• After updating frontend dependencies, reload the browser tab or do a hard refresh so the new card assets are actually loaded.

If you're running an outdated version, update first and see if your issue is resolved before proceeding.

---

Tip

ChoreOps includes built-in backup and restore capabilities. Before troubleshooting complex issues, you may want to create a manual backup or review 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 ChoreOps

Before checking logs, enable debug logging for the integration:

1. Go to Settings → Devices & Services → Integrations.
2. Find ChoreOps 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 choreops 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 entities directly, perform actions, and observe 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.alex_choreops_chore_status_brush_teeth	Should show "pending"
Claim the chore	Press button.alex_choreops_chore_claim_brush_teeth	Button action should be accepted and status should progress
Confirm the claim in chore status	sensor.alex_choreops_chore_status_brush_teeth	Status should change to "claimed"
Check pending approvals	Look at sensor.alex_choreops_ui_dashboard_helper → pending_approvals attribute	Should show chore entries with approval/disapproval button IDs
Approve/disapprove	Press button.alex_choreops_chore_approval_brush_teeth or button.alex_choreops_chore_disapproval_brush_teeth	Status should move to "approved" or return to "pending"
Confirm approval in chore status	sensor.alex_choreops_chore_status_brush_teeth	Status should change to "approved" or revert to "pending"
Confirm removed from pending approvals	Look at sensor.alex_choreops_ui_dashboard_helper → pending_approvals attribute	Chore should no longer appear in the list

📸 Example Screenshot:

---

5️⃣ If requested, download diagnostics or access the ChoreOps data file

🚨 Privacy Note:

• The diagnostics file and storage data contain all ChoreOps data, including user 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 user 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 ChoreOps and click on it.
3. Click the three dots (⋮) menu.
4. Select Download diagnostics.
5. A JSON file will be downloaded containing all your ChoreOps data in an organized format.

This diagnostics file contains everything the integration stores, including:

• All users 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 ChoreOps integration stores its data in:

/config/.storage/choreops/choreops_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/choreops/choreops_data
3. Open and review the file. Copy the text and share as requested.

📸 Example Screenshot:

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 choreops_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.
Dashboard cards fail or render incorrectly	Update frontend dependencies such as button-card in HACS, then reload the page and test again.
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_choreops_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, clear and structured reports allow maintainers to spend more time improving ChoreOps and less time requesting missing details.

Thank you for helping improve ChoreOps! 👍