Troubleshooting and pre-removal checks

Find the failing layer first

Narrow the failure instead of changing every setting at once. This order avoids drawing conclusions from checks that depend on a previous failed step.

Common cases

401: Public credentials or an application session?

• Public Basic Auth credentials may be missing or incorrect. Use a new/clean browser session with controlled test credentials.
• Compare the same request directly at localhost; your application's own 401 differs from the public password check.
• Check whether the webhook client can send Basic Auth. Do not disable application authorization to resolve a public password issue.

503: Is sharing paused?

• Inspect pause for the intended LocalTR link. Pause affects new requests.
• Open the local service directly to distinguish a 503 from your app or another intermediary. A 503 response alone does not establish pause as its cause.

Disconnected: Separate the Mac, service and network

• Check that the Mac is awake and LocalTR and the development server are running.
• Check localhost first, then the local name, then the public URL from another network. After sleep or a network change, recheck the failing layer.
• Reconnection attempts are bounded; do not assume that the same address will remain continuously available.

A local name does not open on a phone

• For a local address, inspect same-network reachability and the client's DNS/multicast behavior. A QR code carries an address; it does not establish name resolution.
• For local HTTPS, check trust on the phone separately; trust on the Mac does not transfer to it.
• For a public URL, check the Mac, tunnel and internet connection rather than assuming the same-network requirement applies. Distinguish local and public links.

Prepare a support request

Include the app and macOS versions, approximate time, steps that passed and a redacted error. Remove Authorization, Cookie, license keys, user data and root CA private keys. Email info@localtr.dev; there is no guaranteed response time.

Safety checks before removal

These are safety prechecks, rather than a complete helper, certificate-trust and data-cleanup procedure verified for every release. Removing the app from Applications does not establish that those resources were also removed.

1. Close public links and local service shares; check that the app is no longer being served.
2. Identify local domains managed by LocalTR. Do not bulk-delete hosts entries belonging to other tools.
3. Keep a redacted copy of any necessary error evidence. Review capture and record files before sharing or clearing them.
4. Establish ownership of helper and CA records. If ownership is unclear, do not run deletion commands or target other tools' certificates.

Ask support for removal or trust-removal steps appropriate to your version. Do not reset system trust or the entire hosts file, or include passwords, license keys or CA private keys in a support message.

LocalTR version:

macOS version:

Approximate time:

Steps followed:

Expected result:

Actual result:

Redacted error message: