Troubleshooting

Quick Checks

Before deep troubleshooting:

• Confirm you are on the latest app release.
• Verify your active branch is correct.
• Make sure your local machine clock is accurate.
• Restart the app once to clear transient UI/runtime states.
• Confirm setup state: incomplete setup always routes users to onboarding.

Sync Issues

If data is not appearing across devices:

• Ensure each device is signed into the correct branch scope.
• Check sync server connectivity and endpoint configuration.
• Validate that branch-level permissions allow the affected action.
• Confirm pending local changes are not blocked by conflicts.
• Verify Sync Target is not set to No sync (local-only).
• For server sync, verify connection code/token and server URL from Settings → General → Database.
• For LAN sync, confirm both devices are on the same network and trusted pairing is complete.

LAN Sync Specifics

• Firewall Issues: Ensure that Holy Resource is permitted to communicate over your local network in your OS firewall settings.
• Network Isolation: Some "Guest" Wi-Fi networks prevent devices from seeing each other. Use a private office network for the best results.
• Ethernet vs Wi-Fi: While it works on both, a wired Ethernet connection provides the most stable experience for large databases.
• Can’t see the other device? Make sure LAN Sync is started on both devices and both are connected to the same Wi-Fi/Ethernet.
• Pairing fails (wrong church/branch): Pairing codes only work for the same church and the same branch.

Permission Denied Errors

If a feature is visible but actions fail:

• Re-check the assigned role and resource-action permissions.
• Verify the user has access to the active branch.
• Confirm the action is not guarded by a stricter permission gate.
• Re-check in Settings → Users & Permissions and Settings → Branches (branch role + resource-action rights).

Volunteer Scheduling Issues

If the volunteer schedule looks wrong or the replacement flow seems stuck, start with the simple inputs before assuming the system is at fault.

Check that volunteer records are current, especially ministry, status, roles, and availability. Check that role definitions are still active and clearly mapped to the right ministries. Then verify that the correct branch is active and that the schedule was generated for the intended dates and events.

If a replacement request is not moving forward, open the volunteer replacement queue and see whether the role is showing as an open vacancy, an active offer, or already filled. In many cases the issue is not that the offer failed to exist. It is that the offer expired, the volunteer did not respond, or a coordinator still needs to act.

Volunteer Offer Response Problems

If a volunteer says they tapped the offer but nothing useful happened, walk through these checks in order:

• Ask them to open the message again in a normal browser if the app did not launch cleanly.
• Confirm they are signed into Holy Resource with the account they normally use for serving.
• Confirm they are looking at the correct branch or church workspace.
• Ask whether the offer may already have been accepted by someone else.

If the offer still cannot be used, resend it from the coordinator side using the manual copy-link option rather than retyping the instructions.

Messaging Delivery Problems

If reminders, updates, or replacement messages are not arriving, separate the issue into two parts: sending and contact data.

First confirm the messaging setup screen is healthy and its test buttons are still passing. Then confirm the person's email address or phone number is saved correctly in the church records. If your team needs to keep moving while you investigate, use the manual resend workflow from the volunteer queue or another approved church channel.

Kids Wing & Check-in Issues

If teams report issues during services, check these in order:

• Permissions: Confirm the user has required Kids Wing read/write actions in Settings → Users & Permissions.
• Branch Context: Ensure the user is in the correct active branch (check the top-left branch selector).
• Event/Session: Verify the selected event/date matches the operational reality for the check-in session.
• Guardian Authorization: Confirm the guardian is authorized for that specific child in the child's profile.
• Room Assignment: Verify age-range and room status assumptions (e.g., if a room is full or restricted).
• Gateway Setup: If SMS/email notifications fail during check-in or checkout, verify the communication gateway configuration in Settings → Messaging.

Messaging Setup Problems

If the messaging setup screen itself is failing, walk through the checks in a simple order instead of changing many things at once.

If a test button fails immediately, re-enter the account details carefully. Pasted values sometimes include hidden spaces or formatting. If SMS fails while the key looks correct, double-check the sending number format and confirm the church account is allowed to send from that number.

If regional routing is not being used, confirm that the route is switched on, the countries are selected, and the provider details are still valid. If the email backup path fails, review the host, port, username, password, and sender email carefully, then confirm the backup switch is actually turned on before testing again.

If backup sending worked before but suddenly seems unused, save the screen again, confirm the backup path is still enabled, and rerun a real test.

Login & Onboarding Issues

• If login keeps redirecting, verify setup completion first.
• If onboarding says owner already claimed, switch to Join flow with invite code.
• If join onboarding says pending online verification, connect that device to the internet once and retry Complete Setup.
• If join onboarding rejects the email, confirm you are using the exact email address the invite was created for.
• If join onboarding is waiting on a verification code, confirm the invite recipient can receive email and enter the newest 6-digit code before it expires.
• If ownership recovery fails, verify owner email exactly matches checkout owner email.

Performance & Stability

If screens feel slow or freeze:

• Close heavy background apps and retry.
• Reduce very large table exports/imports into smaller batches.
• Verify the local database file is not on a failing disk.

Import/Restore Issues

• Use import preview first; do not run blind imports in production.
• If import is blocked for church mismatch, confirm you selected the correct church backup.
• If conflicts are detected, choose the correct policy (Abort, Skip, or Overwrite) for your recovery plan.

Manual database copy or restore problems

If the church manually copied the working database into Holy Resource's app-data folder, check these basics first:

• Close Holy Resource completely before replacing the files.
• Copy holy_resource.db.
• If holy_resource.db-wal and holy_resource.db-shm exist beside that database, copy those too as the same restore set.
• If the issue started right after an app update, try Restore Latest Upgrade Backup in Recovery Mode before doing a manual file rollback.
• Reopen Holy Resource and read the Recovery Mode details before resetting the baseline.

If the main database was copied without its matching WAL/SHM files, the app may open into Recovery Mode because the copied state can be incomplete or out of sync with the last trusted baseline.

Import and Export Problems

If import/export is failing, separate the problem into the correct category first. The fastest way to waste time is to troubleshoot a normal table import as if it were a workspace restore problem.

Normal table import issues

For routine CSV/XLSX imports from module screens:

• Confirm the file is actually .csv, .xlsx, or .xls.
• Confirm the file is under the import size and row/column limits.
• Confirm the expected headers are on the first row.
• Confirm the right branch is active before importing.
• Use the built-in template if the source file was created by hand.
• Review Smart Import notes and the preview before confirming.

If the preview looks wrong, stop and fix the source file first.

Common CSV issues

If a CSV import behaves strangely, check for:

• renamed or missing headers
• extra delimiter characters introduced by manual editing
• rows with embedded notes or addresses that contain line breaks
• a CSV saved with unusual encoding by another spreadsheet tool
• hidden blank columns near the beginning of the file

Common Excel issues

If an Excel import behaves strangely, check for:

• the real data being on a different sheet than the first one
• merged header cells
• decorative top rows above the real header row
• formula-generated display values that do not match the expected import shape
• workbook exports from another system that include extra summary sheets first

If you encounter an "integrity mismatch" during import/export

Treat that carefully.

Routine module import/export work should not normally trigger workspace integrity enforcement just because a file was chosen.

If you hit an integrity mismatch while importing a CSV or Excel file from a normal module screen:

1. Stop and do not assume that is expected behavior.
2. Confirm you were doing a table import, not a restore or backup recovery.
3. Restart the app and retry with the same file once.
4. Retry using the built-in template structure if the source file is messy.
5. Record the exact module, file type, and error message.
6. Escalate if the same normal import consistently triggers integrity recovery.

If support needs the exact recovery instructions, use the step-by-step path in the integrity guide instead of improvising:

• See Step-By-Step Solution For Recovery Mode in Integrity Enforcement
• Use that page's Safe path when you believe the current data is correct when the church has verified the current machine is the right database
• Use that page's Safe path when you are not sure the current data is correct when the church still needs records/finance/admin review

In short: ordinary table import/export should behave like module data handling, not like a trusted-workspace replacement event.

If the message instead mentions that the database appears newer than the saved baseline, or that several protected scopes changed after files were copied manually, treat that as a restore-state problem first, not an import-template problem.

Still Stuck?

Capture these details before escalating:

• app version
• operating system
• exact error message
• steps to reproduce
• whether issue is branch-specific or global