> For the complete documentation index, see [llms.txt](https://netfluss.ranagmbh.de/llms.txt).
> Use it to discover all available pages before exploring further.

# Fix install and runtime issues

Diagnose and fix common NetFluss problems including VPN connection errors, high CPU from nettop, frozen download rates, DNS switch failures, menu bar display issues, install errors, and router monitoring problems.


## App will not open or shows a Gatekeeper or damaged app warning

Gatekeeper sometimes blocks apps downloaded from the internet, or reports that the app is damaged, even when the download is valid.

<Callout kind="info">

NetFluss is notarized and signed with a Developer ID. Gatekeeper should allow it to run once macOS recognizes it as an installed application.

</Callout>

<Steps>
  <Step title="Move NetFluss to Applications" icon="folder" titleType="p">

    - Drag `NetFluss.app` into your `/Applications` folder if it is not already there.
    - Launch NetFluss from `/Applications` or Spotlight instead of running it from the Downloads folder.

  </Step>

  <Step title="Re-download from the official release" icon="download" titleType="p">

    - Delete the existing `NetFluss.app`.
    - Download the latest zip from the official NetFluss releases page.
    - Unzip the download and move the new `NetFluss.app` into `/Applications` again.

  </Step>

  <Step title="Override the first launch warning" icon="shield" titleType="p">

    - Try to open NetFluss. If macOS shows a warning, open **System Settings → Privacy & Security**.
    - Scroll to the security section and look for a message about NetFluss being blocked.
    - Click **Allow Anyway**, then launch NetFluss again from `/Applications`.

  </Step>
</Steps>

If NetFluss still does not open after reinstalling and allowing it in Privacy & Security, capture any exact error text and contact support.

---

## NetFluss icon is missing from the menu bar

NetFluss runs as a menu bar app. If you do not see the icon, either the app is not running or macOS is hiding the icon.

<Steps>
  <Step title="Confirm NetFluss is running" icon="terminal" titleType="p">

    - Open **Activity Monitor** and search for `NetFluss`.
    - If you do not see it, open `/Applications/NetFluss.app` again.

  </Step>

  <Step title="Reveal hidden menu bar icons" icon="monitor" titleType="p">

    - On macOS, some menu bar icons hide behind a chevron or section on the right.
    - Click any chevron or overflow indicator in the menu bar and look for the NetFluss icon.
    - Drag the icon out to pin it, if macOS allows reordering.

  </Step>

  <Step title="Quit and relaunch NetFluss" icon="refresh-cw" titleType="p">

    - If you see NetFluss in Activity Monitor but not in the menu bar, quit the process from Activity Monitor.
    - Relaunch `/Applications/NetFluss.app` and watch for the icon to appear in the menu bar.

  </Step>
</Steps>

If the icon still does not appear, try restarting macOS and launching NetFluss again after the restart.

---

## Preferences window is too large or does not seem resizable

On smaller screens, the NetFluss preferences window can feel too tall to reach the lowest checkboxes or controls.

<Callout kind="info">

From version 1.9.2, the preferences window is resizable on smaller screens. You can drag the edges to shrink the window height and reveal controls that were previously off-screen.

</Callout>

<Steps>
  <Step title="Update to NetFluss 1.9.2 or later" icon="download" titleType="p">

    - Quit NetFluss if it is running.
    - Download NetFluss 1.9.2 or a later version from the official releases page.
    - Move the new `NetFluss.app` into `/Applications`, replacing the old version, and launch it again.
    - Open **Preferences** from the NetFluss popover or menu.

  </Step>

  <Step title="Resize the preferences window" icon="monitor" titleType="p">

    - Move your pointer to any edge or corner of the preferences window.
    - Even if macOS does not show a resize cursor because of a macOS and SwiftUI limitation, click and drag the window edge.
    - Drag the bottom edge upward until all checkboxes and controls fit on your screen.

  </Step>
</Steps>

If the window still does not resize after updating to 1.9.2 or later, confirm you are running the updated app from `/Applications` and not an older copy from another folder.

---

## Menu bar or popover jumps when speeds change

A layout bug in older NetFluss versions can cause the menu bar label or popover to shift left and right as the numbers change width, for example when speeds move from `999 KB/s` to `1.2 MB/s`.

<Steps>
  <Step title="Update to NetFluss 1.9 or later" icon="download" titleType="p">

    - Quit NetFluss if it is running.
    - Download NetFluss 1.9 or later from the official releases page.
    - Move the new `NetFluss.app` into `/Applications`, replacing the old version, and launch it again.
    - Watch the menu bar while speeds change to confirm that the icons and popover now stay in a fixed position.

  </Step>
</Steps>

Version 1.9 uses a fixed-width container for the menu bar display so other icons no longer jump when values change.

---

## Top Apps shows no data

Top Apps reads per-connection byte counts from the system using `netstat -n -b -v` and only shows processes with active TCP or UDP connections. If no app currently has an active connection, the list remains empty.

<Callout kind="info">

Users have reported seeing an empty Top Apps view even though the feature is enabled. In these cases, the issue was that no app had active network traffic at that moment, not a missing permission.

</Callout>

<Callout kind="info">

On macOS 15, Top Apps requires NetFluss 1.7.1 or later. A bug in earlier NetFluss versions on macOS 15 can prevent Top Apps from showing data even when connections are active.

</Callout>

<Steps>
  <Step title="Generate active network traffic" icon="zap" titleType="p">

    - Open a browser and load a few websites, start a video stream, or download a file.
    - Keep the traffic running while you view the NetFluss popover.

  </Step>

  <Step title="Confirm Top Apps is enabled" icon="settings" titleType="p">

    - Open the NetFluss popover and go to its preferences or settings.
    - Ensure the Top Apps feature is turned on.

  </Step>

  <Step title="Reopen the NetFluss popover" icon="play-circle" titleType="p">

    - Close the popover if it is open, then click the NetFluss menu bar icon again.
    - Check whether apps with active TCP or UDP connections now appear in the Top Apps list.

  </Step>
</Steps>

If Top Apps stays empty even while streaming or downloading data, note your macOS version and share details via the GitHub issue tracker, referencing the existing discussion in issue 7.

---

## Top Apps is cluttered with background processes

Background services such as `mDNSResponder` or other system daemons can appear in Top Apps when they use bandwidth, which can push your actual apps off the list.

<Steps>
  <Step title="Hide noisy background apps from Top Apps" icon="minus" titleType="p">

    - Open the NetFluss popover and go to **Preferences → Top Apps**.
    - In **Apps to Hide**, find and select the background processes you do not want to see.
    - Remember that this list shows processes that used bandwidth in the last 60 seconds, so recently active apps appear here.
    - Return to the popover and confirm that the hidden apps no longer take up slots in the Top Apps list, leaving more room for the apps you care about.

  </Step>
</Steps>

Hiding background apps does not affect their network activity; it only cleans up the Top Apps view.

---

## Wi‑Fi SSID or band is missing

Wi‑Fi SSID and band information come from CoreWLAN, which on macOS can require Location Services access to expose SSID details.

<Callout kind="alert">

If you deny Location Services access when macOS first prompts for it, NetFluss cannot show SSID or band details until you re-enable access in System Settings.

</Callout>

<Steps>
  <Step title="Look for the Location Services prompt" icon="info" titleType="p">

    - The first time NetFluss tries to read Wi‑Fi SSID details, macOS may show a Location Services dialog.
    - When prompted, grant access so NetFluss can display SSID and band information.

  </Step>

  <Step title="Re-enable access in System Settings" icon="settings" titleType="p">

    - Open **System Settings → Privacy & Security → Location Services**.
    - Find NetFluss in the app list and enable Location Services for it.
    - Restart NetFluss and check the Wi‑Fi SSID and band fields again.

  </Step>
</Steps>

If the SSID or band are still blank after granting Location Services access, verify that your Mac is connected to Wi‑Fi and not using Ethernet only.

---

## External IP is missing or shows the wrong IP version

External IP issues usually fall into two categories: the IP address is blank, or the address shows IPv6 when you want to see IPv4 instead.

<Steps>
  <Step title="Update to NetFluss 1.9 or later for reliable External IP" icon="download" titleType="p">

    - Quit NetFluss if it is running.
    - Download NetFluss 1.9 or later from the official releases page.
    - Move the new `NetFluss.app` into `/Applications`, replacing the old version, and launch it again.
    - Check the External IP section in the popover to confirm that an address now appears consistently. NetFluss 1.9 uses ipwho.is with an api.ipify.org fallback for improved reliability.

  </Step>

  <Step title="Choose IPv4 or IPv6 in Appearance preferences" icon="settings" titleType="p">

    - Open the NetFluss popover and go to **Preferences → Appearance**.
    - Find the **External IP** setting and choose whether to display your external IPv4 or IPv6 address.
    - On dual-stack networks, NetFluss 1.9.1 and later default to IPv4, but you can switch to IPv6 if you prefer.
    - Return to the popover and verify that the External IP now shows the IP version you selected.

  </Step>
</Steps>

If the External IP field is still blank after updating and checking preferences, test your internet connection in a browser and try again later in case the lookup services are temporarily unavailable.

---

## Too many adapters and scrolling behavior

VPN clients and other tools often create many virtual network adapters. NetFluss lets you rename, reorder, and hide adapters, and caps the visible list so the popover remains usable.

<Callout kind="info">

From version 1.7, the adapter list in the popover scrolls when more than six interfaces are active. The list shows up to six adapter cards at once, and you can scroll to see the rest. IP addresses and Top Apps stay visible below the list.

</Callout>

<Steps>
  <Step title="Rename and reorder important adapters" icon="edit" titleType="p">

    - Use NetFluss preferences to rename adapters that matter to you and move them near the top of the list.
    - Keep in mind that some VPN tools create new interfaces each time they connect, so names might not stay attached to the same underlying device, as reported in issue 6.

  </Step>

  <Step title="Hide inactive or other adapters" icon="minus" titleType="p">

    - In preferences, enable options to hide inactive adapters.
    - Use any available setting to hide other or virtual adapters that you do not need to see.

  </Step>

  <Step title="Scroll through the adapter list" icon="arrow-right" titleType="p">

    - When more than six interfaces are active, move your mouse over the adapter section in the popover.
    - Scroll to view additional adapters while keeping IP addresses and Top Apps visible.

  </Step>
</Steps>

If adapter clutter remains a problem with heavy VPN usage, consider limiting which VPN tools run at the same time so they create fewer simultaneous virtual interfaces.

---

## Fritz!Box bandwidth data is missing or not updating

Fritz!Box Bandwidth Monitoring shows the total WAN download and upload rates from your Fritz!Box router directly in the NetFluss popover.

<Callout kind="info">

NetFluss queries Fritz!Box bandwidth via the official TR-064 API. Fritz!Box does not require authentication for this specific bandwidth data, so NetFluss does not need your router password for the feature to work.

</Callout>

<Callout kind="info">

Fritz!Box Bandwidth Monitoring is experimental in NetFluss 1.10. Expect some rough edges and share feedback or bug reports so the feature can improve.

</Callout>

<Steps>
  <Step title="Enable Fritz!Box Bandwidth Monitoring in preferences" icon="settings" titleType="p">

    - Open the NetFluss popover and go to **Preferences → Fritz!Box Bandwidth**.
    - Turn on the Fritz!Box Bandwidth Monitoring option if it is disabled.
    - Return to the popover and wait a few seconds to see if Fritz!Box download and upload rates start appearing.

  </Step>

  <Step title="Confirm the Fritz!Box router address" icon="monitor" titleType="p">

    - In **Preferences → Fritz!Box Bandwidth**, check the router address field.
    - Use `fritz.box` if you use the default Fritz!Box hostname, or enter your router's IP address if you changed it.
    - Save the preferences and watch the NetFluss popover to see whether the Fritz!Box bandwidth values begin updating.

  </Step>

  <Step title="Verify Fritz!Box is reachable from your Mac" icon="terminal" titleType="p">

    - Make sure your Mac is connected to the same network as the Fritz!Box (typically the home Wi‑Fi or LAN).
    - Open a browser and try loading `http://fritz.box` or your configured router address to confirm the router responds.
    - If the router page does not load, fix the network or address issue first and then check the Fritz!Box bandwidth section in NetFluss again.

  </Step>
</Steps>

If Fritz!Box bandwidth still shows no data or does not refresh after confirming preferences and connectivity, note your NetFluss version, Fritz!Box model, and router firmware version and share feedback via the GitHub issue tracker.

---

## UniFi or OpenWrt monitoring is missing or will not connect

UniFi and OpenWrt monitoring in NetFluss 1.11 rely on reaching your local controller or router, using valid credentials, and reading stored credentials from Apple Keychain.

<Callout kind="info">

NetFluss stores UniFi and OpenWrt credentials in Apple Keychain so macOS can encrypt them and control access. NetFluss uses these credentials locally on your Mac and does not send them to any external service.

</Callout>

<Steps>
  <Step title="Confirm the controller or router is reachable" icon="monitor" titleType="p">

    - Make sure your Mac is connected to the same network as your UniFi controller or OpenWrt router.
    - Open a browser and try loading the UniFi controller URL or the OpenWrt LuCI web interface using the same host and port you configured in NetFluss.
    - If the page does not load, fix the network or address issue first, then return to NetFluss and check the UniFi or OpenWrt section again.

  </Step>

  <Step title="Re-enter UniFi or OpenWrt credentials in NetFluss" icon="edit" titleType="p">

    - Open the NetFluss popover and go to **Preferences** for UniFi or OpenWrt monitoring.
    - Carefully re-enter the hostname, username, password, and any required port or protocol fields.
    - Save the preferences and wait a few seconds to see whether NetFluss begins showing UniFi or OpenWrt metrics.

  </Step>

  <Step title="Allow Apple Keychain access when prompted" icon="shield" titleType="p">

    - If macOS shows a dialog asking whether NetFluss may access a Keychain item related to UniFi or OpenWrt, choose to allow access.
    - Select the option that allows NetFluss to access this item every time to avoid repeated prompts.
    - After allowing access, watch the NetFluss popover to confirm that UniFi or OpenWrt monitoring updates.

  </Step>

  <Step title="Reset stored credentials in Apple Keychain" icon="trash" titleType="p">

    - Open the **Keychain Access** app on your Mac and search for entries whose names mention NetFluss and UniFi or OpenWrt.
    - Delete the specific NetFluss UniFi or OpenWrt Keychain item, leaving other unrelated items intact.
    - Return to NetFluss preferences for UniFi or OpenWrt monitoring, re-enter your credentials, and save again so NetFluss can create a fresh Keychain entry.

  </Step>
</Steps>

If UniFi or OpenWrt monitoring still does not connect after these steps, note your NetFluss version, UniFi or OpenWrt firmware version, and any error text shown in NetFluss, then share details via the GitHub issue tracker.

---

## Popover buttons are unresponsive after using About or Preferences

Older versions of NetFluss had a bug where, after opening and closing the About window, footer buttons in the popover could stop responding.

<Callout kind="alert">

This bug was fixed in version 1.5 by changing window activation behavior. If you see unresponsive buttons, you are likely on an older build and should update.

</Callout>

<Steps>
  <Step title="Update NetFluss to the latest version" icon="download" titleType="p">

    - Quit NetFluss if it is running.
    - Download the most recent release zip from the official NetFluss releases page.
    - Move the new `NetFluss.app` into `/Applications`, replacing the old version, and launch it again.

  </Step>

  <Step title="Test the popover after updating" icon="check-circle" titleType="p">

    - Click the NetFluss menu bar icon to open the popover.
    - Open the About or Preferences window, close it, and then try the footer buttons again.
    - Confirm that the buttons respond as expected.

  </Step>
</Steps>

If the popover still ignores clicks after updating, restart macOS and test again. If the issue persists, include your NetFluss version and macOS version when you contact support.

---

## VPN: "Bad CPU type in executable" on older Intel Macs

If you see `The operation couldn't be completed. Bad CPU type in executable` when trying to connect a WireGuard VPN profile, this typically occurs on older Intel-based Macs, particularly those running macOS via OpenCore Legacy Patcher (OCLP).

<Callout kind="alert">

This issue is currently open and under investigation. The NetFluss helper binary may not include a full x86_64 slice for all older Mac architectures.

</Callout>

<Steps>
  <Step title="Check your Mac architecture" icon="cpu" titleType="p">

    - Open **About This Mac** and confirm whether your Mac uses Apple Silicon or an Intel processor.
    - If you are on an older Intel Mac (especially pre-2017 models), this error is a known compatibility issue.

  </Step>

  <Step title="Try OpenVPN or IKEv2 instead" icon="shuffle" titleType="p">

    - If your VPN provider offers OpenVPN or IKEv2/IPsec profiles, try importing and connecting with one of those protocols instead of WireGuard.
    - IKEv2 uses the native macOS VPN stack and does not rely on bundled helper binaries.

  </Step>

  <Step title="Report your setup on GitHub" icon="github" titleType="p">

    - Open an issue on the NetFluss GitHub repository with your Mac model, macOS version, and whether you are using OCLP.
    - Reference issue #48 so the maintainer can track the compatibility fix.

  </Step>
</Steps>

---

## VPN: OpenVPN "Could not reach the management interface"

If you see `Could not reach the OpenVPN management interface` when connecting an OpenVPN profile, the most common cause is that the `openvpn` command-line tool is not installed or not accessible on your system.

<Callout kind="info">

NetFluss bundles a signed `openvpn` binary, but if you installed NetFluss via Homebrew, the helper may not be in the expected path. Ensure you are running the latest NetFluss version.

</Callout>

<Steps>
  <Step title="Update NetFluss to the latest version" icon="download" titleType="p">

    - Quit NetFluss if it is running.
    - Download the latest release from the GitHub releases page and move it to `/Applications`.
    - Relaunch NetFluss and try connecting your OpenVPN profile again.

  </Step>

  <Step title="Verify the profile is valid" icon="file-check" titleType="p">

    - Open your `.ovpn` file in a text editor and confirm it contains valid server and certificate directives.
    - If the profile uses a provider-patched directive such as `scramble` or XOR obfuscation, NetFluss cannot run it with the bundled upstream `openvpn`.

  </Step>

  <Step title="Check for leftover OpenVPN processes" icon="terminal" titleType="p">

    - Open Terminal and run `pgrep -l openvpn` to check for stale processes.
    - If you see any, kill them with `kill <PID>` and retry the connection from NetFluss.

  </Step>
</Steps>

If the error persists after updating and verifying the profile, open an issue on GitHub with your NetFluss version, macOS version, and the `.ovpn` file (with sensitive values redacted).

---

## VPN: WireGuard shows "connection stopped" but the tunnel is still active

In some cases, NetFluss reports `The VPN connection stopped` and marks a WireGuard profile as disconnected, even though the tunnel is still working — `wireguard-go` is running, the `utun` interface is up, and traffic flows normally.

<Callout kind="alert">

This is a known issue (#50) caused by a name mismatch between the internal handle NetFluss creates and the actual interface name that `wg-quick` assigns. The VPN tunnel itself continues to work — only the NetFluss status display is incorrect.

</Callout>

<Steps>
  <Step title="Verify the tunnel is actually working" icon="check-circle" titleType="p">

    - Open a browser and load a website to confirm internet access works through the tunnel.
    - Run `ifconfig | grep utun` in Terminal to check that the WireGuard interface is still up.

  </Step>
</Steps>

<Callout kind="info">

The tunnel remains active and secure despite the incorrect status display. Reconnecting from NetFluss may spawn additional `wireguard-go` processes and leave temporary config files in `/private/tmp/`. If you reconnect multiple times, check for orphaned processes using `pgrep -l wireguard` and clean up stale files in `/private/tmp/` that start with `nf`.

</Callout>

If you encounter this issue, report it on GitHub with reference to issue #50, including your NetFluss version and macOS version.

---

## High CPU usage from the nettop process

On some Macs, the `nettop` subprocess used by NetFluss can intermittently cause high CPU usage, which increases energy impact and power consumption.

<Callout kind="info">

This issue (#45) has been reported on Apple Silicon Macs running recent macOS versions. NetFluss 2.3 replaced continuous `nettop` usage with a kernel-statistics client that runs at approximately 0% CPU, but `nettop` may still be used for Top Apps when the popover is open or as a fallback.

</Callout>

<Steps>
  <Step title="Restart NetFluss" icon="refresh-cw" titleType="p">

    - Quit NetFluss from the menu bar or Activity Monitor.
    - Relaunch NetFluss from `/Applications`.
    - The high CPU spike from `nettop` should disappear after restarting.

  </Step>

  <Step title="Update to NetFluss 2.3 or later" icon="download" titleType="p">

    - NetFluss 2.3 introduced a kernel-statistics client that replaces continuous `nettop` for most operations.
    - Download the latest version from the GitHub releases page and move it to `/Applications`.

  </Step>

  <Step title="Reduce popover frequency" icon="settings" titleType="p">

    - If the issue recurs, especially after your Mac wakes from sleep, try increasing the refresh interval in **Preferences → General → Update**.
    - The `nettop` spike is most noticeable when the popover is open and Top Apps is active.

  </Step>
</Steps>

If high CPU persists after updating to 2.3 or later, use the hidden **Copy Network Diagnostics** action (hold Option and right-click the NetFluss menu bar icon) to capture 30 seconds of diagnostic data, and share it on GitHub referencing issue #45.

---

## Download rate stuck at 0.00 B/s

If the download rate always shows `0.00 B/s` while the upload rate works correctly, this is a known issue on some macOS configurations where the kernel `ifi_ibytes` counter is frozen on the active Wi-Fi or Ethernet adapter.

<Callout kind="info">

This has been reported in managed/MDM profiles (issue #31) and with NAS file transfers over SMB (issue #30). NetFluss 2.3 includes a fallback that detects the broken adapter and substitutes a per-process inbound rate.

</Callout>

<Steps>
  <Step title="Update to NetFluss 2.3 or later" icon="download" titleType="p">

    - NetFluss 2.3 detects frozen adapter counters and falls back to a kernel-statistics client to calculate the download rate.
    - Download the latest version from the GitHub releases page and move it to `/Applications`.

  </Step>

  <Step title="Check if the fallback is active" icon="activity" titleType="p">

    - After updating, monitor the download rate while downloading a file.
    - If the rate now shows correctly, the fallback mechanism is working.
    - If it still shows `0.00`, try quitting and relaunching NetFluss.

  </Step>

  <Step title="Run Network Diagnostics" icon="terminal" titleType="p">

    - Hold **Option** and right-click the NetFluss menu bar icon.
    - Choose **Copy Network Diagnostics…** to capture 30 seconds of per-interface byte counters to your clipboard.
    - Paste the output into a GitHub issue referencing #30 or #31, along with your macOS version and whether you use a managed profile.

  </Step>
</Steps>

---

## DNS switch fails: "active network service could not be identified"

If the DNS Switcher shows `active network service could not be identified` when you try to switch DNS providers, this is a known issue that was reported on Wi-Fi connections (issue #36).

<Callout kind="info">

This was fixed in a NetFluss update. The fix applies DNS changes to all enabled network services, not just the primary one.

</Callout>

<Steps>
  <Step title="Update to the latest NetFluss version" icon="download" titleType="p">

    - Quit NetFluss and download the latest release from GitHub.
    - Move the new `NetFluss.app` to `/Applications` and relaunch.
    - Try switching DNS again from the popover.

  </Step>

  <Step title="Check the privileged helper is installed" icon="shield" titleType="p">

    - Go to **Preferences → General → System access**.
    - Click **Install Privileged Helper…** and confirm the status shows as enabled.
    - If the helper fails to install, restart your Mac and try again.

  </Step>

  <Step title="Use networksetup as a temporary workaround" icon="terminal" titleType="p">

    - If the issue persists, you can switch DNS manually in Terminal:

    ```bash
    sudo networksetup -setdnsservers Wi-Fi 1.1.1.1 1.0.0.1
    ```

    - Replace `Wi-Fi` with your active network service name and the IP addresses with your preferred DNS servers.

  </Step>
</Steps>

---

## Menu bar font size has no effect in the default style

If changing the font size in Preferences only adds or removes empty space behind the text but the actual font size does not change, this is a known bug in NetFluss 2.2 (issue #40).

<Callout kind="info">

This only affects the default (Standard) menu bar style. The Pill and Dashboard styles apply font size changes correctly.

</Callout>

<Steps>
  <Step title="Update to NetFluss 2.2.1 or later" icon="download" titleType="p">

    - The font size rendering bug was fixed shortly after the 2.2 release.
    - Download the latest version from GitHub and move it to `/Applications`.

  </Step>

  <Step title="Switch to a different style as a workaround" icon="palette" titleType="p">

    - If you cannot update immediately, go to **Preferences → Appearance** and switch to the Pill or Dashboard style.
    - Font size changes apply correctly in these styles.

  </Step>
</Steps>

---

## Stats are cut off on external displays

If the NetFluss menu bar stats display correctly on your Mac's built-in screen but are cropped at the top on external displays, this is a known issue (issue #38) related to macOS display handling.

<Steps>
  <Step title="Update to the latest NetFluss version" icon="download" titleType="p">

    - This issue was fixed in a NetFluss update released after the initial report.
    - Download the latest version from GitHub and move it to `/Applications`.

  </Step>

  <Step title="Check display scaling settings" icon="monitor" titleType="p">

    - Open **System Settings → Displays** and select the affected external display.
    - Try a different scaling option to see if the cropping changes.
    - If the issue persists after updating, report your display model and resolution on GitHub.

  </Step>
</Steps>

---

## Menu bar text colour does not adapt to light/dark appearance

If your menu bar text becomes unreadable when switching between light and dark wallpapers, NetFluss previously required you to manually set the text and arrow colours for each appearance.

<Callout kind="info">

NetFluss 2.4 introduced a "System default" colour option that uses `NSColor.labelColor` to automatically adapt to the menu bar appearance. This was contributed via PR #47.

</Callout>

<Steps>
  <Step title="Update to NetFluss 2.4 or later" icon="download" titleType="p">

    - Download the latest version from GitHub and move it to `/Applications`.

  </Step>

  <Step title="Select System default colour" icon="palette" titleType="p">

    - Go to **Preferences → Appearance**.
    - Set the upload arrow, download arrow, upload number, and download number colours to **System default**.
    - The colours now adapt automatically when you switch between light and dark menu bar appearances.

  </Step>
</Steps>

---

## Fritz!Box returns HTTP 500 when OPNsense is the gateway

If your Fritz!Box bandwidth monitoring fails with an HTTP 500 error, this can happen when an OPNsense firewall is your primary router/gateway and the Fritz!Box is only used as a modem or management device (issue #33).

<Callout kind="info">

In this topology, the Fritz!Box TR-064 API may return errors because it is not the primary routing device. NetFluss 2.1 added native OPNsense monitoring as an alternative.

</Callout>

<Steps>
  <Step title="Set up OPNsense monitoring instead" icon="server" titleType="p">

    - Go to **Preferences → Router → OPNsense**.
    - Enter your OPNsense API key, secret, and host address.
    - Use the test-connection button to verify connectivity before saving.

  </Step>

  <Step title="Disable Fritz!Box monitoring" icon="minus" titleType="p">

    - If the Fritz!Box is only acting as a modem behind OPNsense, disable Fritz!Box bandwidth monitoring in **Preferences → Router → Fritz!Box** to avoid repeated error polling.

  </Step>
</Steps>

---

## Settings page appears blank when opened with Cmd+comma

If opening Settings via the `Cmd + ,` keyboard shortcut shows a blank white page instead of the configuration options, this was a known bug (issue #35) that has been fixed.

<Steps>
  <Step title="Update to the latest NetFluss version" icon="download" titleType="p">

    - The blank settings page bug was fixed in a NetFluss update.
    - Download the latest version from GitHub and move it to `/Applications`.

  </Step>

  <Step title="Use the popover as a workaround" icon="mouse-pointer" titleType="p">

    - If you cannot update immediately, open Preferences by clicking the NetFluss menu bar icon and selecting Preferences from the popover instead of using `Cmd + ,`.

  </Step>
</Steps>

---

## Popover window overflows the screen

If the NetFluss popover is taller than your screen and extends beyond the display boundaries, hiding the bottom status bar, this was a known issue (issue #42) that has been fixed.

<Steps>
  <Step title="Update to NetFluss 2.3 or later" icon="download" titleType="p">

    - NetFluss 2.3 clamps the popover height to the available screen height on shorter displays.
    - Download the latest version from GitHub and move it to `/Applications`.

  </Step>

  <Step title="Reduce visible popover sections" icon="layout" titleType="p">

    - Go to **Preferences → Appearance → Popover sections** and hide sections you do not need.
    - Fewer visible sections reduce the overall popover height.

  </Step>
</Steps>

---

## Blue focus ring stuck around the Wi-Fi reconnect icon

If a persistent blue focus ring appears around the Wi-Fi reconnect icon in the NetFluss popover and never clears, this was a macOS update-related visual bug (issue #21).

<Steps>
  <Step title="Update to the latest NetFluss version" icon="download" titleType="p">

    - This focus ring issue was fixed in a NetFluss update shortly after it was reported.
    - Download the latest version from GitHub and move it to `/Applications`.

  </Step>

  <Step title="Restart NetFluss if the ring persists" icon="refresh-cw" titleType="p">

    - Quit NetFluss from Activity Monitor or the menu bar.
    - Relaunch from `/Applications` and check if the focus ring is gone.

  </Step>
</Steps>