← Documentation

Troubleshooting

Common issues and how to resolve them. If your problem isn't listed here, the diagnostic log at ~/Library/Logs/Lograker/lograker.log carries detailed per-component traces - useful to attach to a bug report.

SSH connection failures

"No route to host" on a .local hostname

macOS asks for Local Network permission the first time any app reaches a Bonjour mDNS hostname (*.local) or a local-network IP (192.168.x.x, 10.x.x.x, fe80::, …). Until you approve the prompt, all such connections silently fail with errors like "No route to host" or NIOConnectionError 1.

Fix:

  1. Look for the Local Network privacy prompt - it may be stacked behind another window or in Notification Center.
  2. Approve it. Restart LogRaker.

If LogRaker has been re-signed (a fresh build), macOS may silently revoke the permission without re-prompting. System Settings ▸ Privacy & Security ▸ Local Network - toggle LogRaker off then on, then relaunch.

Trust prompt loops or "Host key mismatch"

The first connection to a host shows a trust prompt; approving it adds the host to LogRaker's trust ledger (separate from your shell's ~/.ssh/known_hosts).

If the host's key has legitimately changed (server rebuild, rekey), a two-step warning sheet asks to confirm the new key. Accept it to replace the stored fingerprint.

To clear a single host's trust: Settings ▸ Security ▸ select the host ▸ Remove…. This also tears down any active SSH session for that endpoint.

Connection drops after some idle time

LogRaker keeps SSH parents alive with TCP keepalives (15s idle / 15s probes) and SSH-level pings every 30s. If a network device along the path drops idle connections faster than that, you may still see drops. Reconnect is automatic with exponential backoff - but if it's happening constantly, check the diagnostic log for [SSHSession] and [Tailer.SSH] traces.

File access issues (App Store Edition)

If the Stream editor shows a "Path is not accessible" sheet when you save, your file is in a sandbox-blocked location. See Local System Sources ▸ App Store Edition for the list of restricted paths.

Workarounds:

GCP / Firebase issues

Test Connection fails with "permission denied"

Your auth principal (ADC user or service account) lacks roles/logging.viewer on the project. Add it via GCP Console ▸ IAM, or ask the project owner to.

Test Connection succeeds but no Firebase autodetect

The autodetect needs firebase.management.viewer (or broader) on the project. If your credentials are scoped to logging.viewer only, the autodetect call returns 403 and LogRaker silently skips the Firebase tag in the success message. That's not an error - Logging itself works fine.

"Couldn't load gcloud ADC credentials"

Run gcloud auth application-default login in Terminal and re-test. If you've never run it, the credential file at ~/.config/gcloud/application_default_credentials.json does not exist.

LogRaker won't quit / "did not exit within 15s"

Usually a sheet or alert is blocking the quit. Dismiss the sheet (look for stacked windows; check the Dock badge). Force-quitting via Activity Monitor works as a last resort but skips LogRaker's graceful cleanup - pooled SSH sessions may take longer than usual to time out on the server side.

"Install LogRaker in your Applications folder?" on launch

The Web Edition shows this if you launch it from outside your Applications folder - usually straight from a freshly unzipped download in ~/Downloads. macOS runs a downloaded app from a temporary read-only location ("App Translocation"), which stops auto-updates from working. Click Install in Applications and LogRaker copies itself there and relaunches from /Applications, where it can keep itself up to date. You can then delete the copy left in your Downloads. Decline with Don't Install and the prompt simply returns next launch while you're still running from outside Applications. (The App Store Edition never shows this - the Mac App Store already installs it to Applications.)

Diagnostic log

LogRaker writes timestamped tracing to:

The log is rotated at launch once it exceeds 5 MB - the previous contents are kept alongside as lograker.log.old and a fresh log is started.

Each launch begins with a five-line banner so session boundaries stand out. Common tags include KnownHosts, SSHSession, Tailer.SSH, LocalTail, StreamEditor, ServerEditor, Restore, Lifecycle, GCPLoggingClient, GCPOAuth2, SnapshotParity.

Tail it from inside LogRaker by adding a Local Stream pointing at it - dogfood your own log.

To send it to support, choose Help ▸ Send Diagnostics… - it opens an email with the log already attached. (If no mail app is set up, it reveals the log in Finder so you can attach it yourself.) For comments or feature requests without a log, use Help ▸ Send Feedback… instead.