If ZimaClient on macOS stays on “Connecting,” sign out of the client and sign back in before reinstalling the app or changing your ZimaOS server. That exact action restored the verified 2.1.0 source case after several hours of being stuck.
However, do not treat sign-out/sign-in as a universal root-cause fix. The same thread involved both Mac and Android connection symptoms after ZimaOS upgrades, and IceWhale specifically asked about firewalls, VPNs, proxies, ISP changes, and network configuration. A good troubleshooting path separates account/session state from network reachability.
Step 1: Confirm the Server Works Locally
Open the ZimaOS dashboard directly by LAN IP in a browser. If the server works locally but ZimaClient cannot connect, focus on the client/session/remote-access layer.
Step 2: Sign Out and Sign Back In
The original user had already reinstalled ZimaClient and rebooted ZimaOS without success. Logging out of ZimaClient and authenticating again restored the connection.
This suggests stale client/session state was involved, but the thread did not prove exactly which token or network state changed.
Step 3: Check Remote Access in ZimaOS
The current ZimaOS remote access guide says remote access can be turned on or off in Settings → Network.
Make sure it is enabled if you expect ZimaClient to work away from home.
Step 4: Test on the Same LAN
Current ZimaOS onboarding guidance recommends the first connection on the same network. If ZimaClient cannot connect even locally, remote NAT traversal is not the first problem.
Step 5: Check VPN, Proxy, Firewall, and Network Changes
IceWhale support specifically asked whether the user had changed firewall, VPN/proxy, ISP, or network administration before the failure.
Temporarily disable conflicting VPN/proxy clients during diagnosis and confirm macOS local-network permission allows ZimaClient to discover devices.
Step 6: Restart Stuck ZimaClient Processes
The current ZimaClient installation guide recommends using Activity Monitor to close Zima-related processes when the app appears to be running but not behaving correctly.
Step 7: Collect Logs Before Reinstalling Again
Current documentation lists ZimaClient logs on macOS under:
~/Library/Application Support/Zima/logsCollect them immediately after reproducing the issue so support can distinguish discovery, authentication, and remote-network failures.
Use Standard VPN Tools as an Alternative Path
Current ZimaOS also supports Tailscale, WireGuard Easy, Firefly, and NetBird as alternative remote-network options. They do not replace ZimaClient's backup or Finder integration, but they can provide a separate private network path.
The remote connection guide helps compare those layers.
Distinguish Authentication from Connectivity
If the Mac can discover the server but authentication fails, compare the same ZimaOS account in the local web UI. If the account works in the browser but not ZimaClient, the problem is likely client/session state rather than the password itself.
If neither browser nor client can reach the server by IP, troubleshoot the server or LAN first.
Check macOS Local Network Permission
macOS can restrict an application's ability to discover devices on the local network. If ZimaClient does not list a nearby ZimaOS device, review the app's Local Network permission in macOS Privacy & Security settings and restart the client after changing it.
Reset Only the Layer That Is Broken
Do not reset the ZimaOS server, Remote ID, password, and client installation all at once. Change one layer at a time so you know what actually fixed the problem.
The source case is a good example: server reboot and client reinstall did not help; signing out and back in did. That evidence points toward session state rather than a damaged server installation.
When to Use an Alternative Remote Path
If ZimaClient remains unavailable but the server itself is healthy, a separately configured Tailscale or WireGuard path can keep administration available while you collect logs. Use it as an independent network path, not as proof that the ZimaClient issue is fixed.
FAQ
Why did reinstalling ZimaClient not help?
A reinstall may leave account/session or network conditions unchanged. In the verified source case, signing out and back in was the action that restored service.
Why can SMB work while ZimaClient fails?
SMB on the LAN and ZimaClient remote/session connectivity are different layers. One can work while the other is broken.
Where are ZimaClient Mac logs?
Current official documentation lists ~/Library/Application Support/Zima/logs.
Should I reset my ZimaOS password?
Not merely because ZimaClient says Connecting. First verify direct login, sign out/in, network state, and logs.
