HozzDocs
All documentation

When something is wrong

Troubleshooting

Find the message or symptom, then fix it.

Find the message or symptom you see.

Every message, and what it means#

These are the app's exact strings.

  • Health data is locked. Unlock this iPhone and Hozz will continue.

    What it means
    iOS woke Hozz while Health was encrypted.
    What to do
    Unlock the phone. The next pass resumes without skipping records.

  • Health returned no data. Apple does not let Hozz tell a denied type from an empty one.

    What it means
    The type is denied or empty. HealthKit reports both identically.
    What to do
    Check the type in Settings → Health → Data Access & Devices → Hozz. If it is on, you have no data of that type.

  • Health data is unavailable or restricted on this device.

    What it means
    HealthKit itself is off — Screen Time restrictions, or a device without Health.
    What to do
    Check Screen Time content restrictions.

  • Hozz could not reach that folder. It may have been moved, renamed, or signed out.

    What it means
    The folder moved, was renamed, or its cloud drive signed out.
    What to do
    Edit the destination and pick the folder again.

  • Hozz no longer has permission to write to that folder.

    What it means
    The folder resolves but iOS refused the write.
    What to do
    Edit the destination and pick the folder again to re-grant access.

  • The destination refused the data (HTTP …).

    What it means
    The endpoint returned non-2xx. Hozz retries 408, 429 and 5xx; other codes stop.
    What to do
    Check the endpoint logs. Hozz does not log response bodies.

  • Hozz could not reach the destination: …

    What it means
    Wrong host, no route, TLS refusal, or nothing listening.
    What to do
    Confirm the phone can reach it. Use Send a test.

  • This destination is not finished being set up.

    What it means
    A required field, such as the address or the folder, is still empty.
    What to do
    Open the destination and complete it.

  • The delivery was stopped before it finished.

    What it means
    iOS ended the background window, or the app was closed mid-delivery.
    What to do
    Nothing. The cursor stayed put; the next pass resends.

  • Offline — open Hozz on it

    What it means
    A previously used Mac did not answer.
    What to do
    Open Hozz on that Mac and make sure both devices are on the same network.

  • Hozz needs permission to see this network

    What it means
    Local Network access was declined, so Bonjour cannot look for your Mac.
    What to do
    Settings → Hozz → Local Network. You can also add the Mac by web address instead.

The Mac does not appear on the phone#

Check these in order:

  1. Is Hozz open on the Mac?#

    The receiver runs only while the app is open. An unavailable saved Mac shows Offline — open Hozz on it.

  2. Are both devices on the same network?#

    Guest networks, client isolation, unbridged SSIDs and cellular prevent discovery.

  3. Does the phone have Local Network permission?#

    If asked, grant it in Settings → Hozz → Local Network.

  4. Is the Mac reachable at all?#

    A GET to the port answers with a small JSON identification:

    From any machine on the same network
    curl -sv http://your-mac.local:54330/
# {"service":"hozz-receiver","ready":true,"name":"Brandon's Mac"}

    If it answers, add the Mac by web address. Otherwise check the network and Mac.

  5. Give up on the network and use a folder#

    Use a synced folder instead of an inbound connection.

The first sync looks stalled#

A first backfill covers years in short iOS windows. Days or weeks is normal.

Completed types and Mac history should grow. If neither moves across several days despite opening the app, treat it as stuck.

An export came out empty, or smaller than expected#

  • Check the format. GPX contains only workouts with GPS.
  • Check Health permissions. Apple makes denied and empty types indistinguishable. Look at Settings → Health → Data Access & Devices → Hozz.
  • Check the destination's type limit.
  • Check whether backfill reached the type.

Background sync is not running on schedule#

See Background sync. The short checklist:

  • Have you force-quit Hozz? That stops background launches until you open it again.
  • Is Low Power Mode on? It suspends background refresh.
  • Is Settings → General → Background App Refresh on, globally and for Hozz?
  • Is the phone locked when you expect the sync? Health cannot be read while it is.
  • Is the cadence what you think? "When new data arrives" is still capped at hourly by HealthKit for most types.

Opening the app starts a sync, and Sync now forces one immediately.

A destination says it needs attention#

retrying continues automatically; needsAttention stops for you.

If this build cannot recognize a destination setting, it keeps the record and refuses to use it:

  • The unrecognised value is held as-is and written back out untouched, so a build that cannot read a setting cannot erode it either.
  • The destination stays in the list, marked as needing attention, naming which setting and which value it did not understand.
  • Nothing is delivered to it, not even on Sync now, and a connection test refuses rather than reporting it as working.

Editing and saving replaces the original setting.

An unfinished export cannot be continued#

An incompatible unfinished export remains visible with its reason and can be discarded.

The MCP server reports no data#

The path is wrong or nothing has synced. Copy configuration from the Mac app's Assistant tab; see MCP.

Still stuck#

Open an issue. Logs omit Health values, credentials and destination secrets.