Troubleshooting

Start with the message in the Setup Centre or Settings → Integrations. It tells you which part of the route has failed:

1. Musterly must be able to reach the Runner.
2. The Runner must be able to reach UniFi Access.
3. UniFi Access must accept the API token.
4. The connector and Runner must be assigned to the same site.

Test from the Runner machine. A controller may work from your laptop but not from the server because they use different networks or DNS settings.

Runner offline

An Offline Runner has not contacted Musterly recently.

On Linux:

sudo systemctl status musterly-runner
sudo journalctl -u musterly-runner --since "30 minutes ago"

On Windows:

1. Check the Musterly Runner icon in the notification area.
2. Open its menu and read the connection status.
3. Make sure the Windows user has not signed out.
4. Check Launch at login is enabled.

If the Runner is running, test outbound HTTPS to app.musterly.io.

Authentication rejected

UniFi Access answered, but did not accept the token.

1. Sign in to the same UniFi controller used in the connector URL.
2. Check the token has not been removed or rotated.
3. Check its account can read Access devices.
4. Open Settings → Integrations, edit the connector and enter a new token.

Do not paste the token into a support ticket or log.

Host unreachable or connection refused

The Runner cannot open a connection to the controller.

• Check the URL includes https:// and the correct port.
• Try the controller URL from the Runner machine.
• Check the Runner is on the right VLAN, VPN or local network.
• Check firewall rules between the Runner and controller.
• Check the hostname does not point to a different address on the Runner’s network.

DNS failure

DNS turns a hostname into an IP address. Run these checks on the Linux Runner host:

getent hosts app.musterly.io
getent hosts your-unifi-hostname

If the UniFi name only exists on an internal DNS server, make sure the Runner uses that server. Check VPN-specific DNS and split-DNS rules.

On Windows, use:

Resolve-DnsName your-unifi-hostname

Certificate error

The Runner must trust the certificate presented by UniFi Access.

• Check the controller URL matches a name on its certificate.
• Renew an expired certificate.
• If your organisation uses a private certificate authority, install that authority’s root certificate on the Runner machine.
• If HTTPS traffic is inspected, make sure the inspection certificate is trusted on the Runner.

Do not work around the error by turning off certificate checking.

Request timeout

A timeout means the connection started but did not finish in time. Check routing, firewall inspection, a busy controller and any proxy between the two systems. Your network team can use the Runner address, destination address and time of the failed request to find the matching firewall log.

No initial sync

1. Open Settings → Integrations.
2. Check the Runner is Online.
3. Check the connector is active.
4. Edit the Runner and assign the connector.
5. Check the Runner and connector use the same site.
6. Wait for the next sync, then refresh the Setup Centre.

Synced but no live events

1. Use a real credential at a door.
2. Confirm the event appears in UniFi Access.
3. Open Doors and check the door is not Ignored.
4. Check the correct site in Musterly.
5. Return to the Setup Centre and refresh.

To finish setup, the event must be from the last 24 hours.

Installer cannot reach GitHub

The Linux installer and Runner updater use GitHub for releases. Allow the destinations in Networking and security, then test:

sudo curl -4 -I --connect-timeout 10 --max-time 30 \
  https://api.github.com/repos/Musterly/musterly-runner-dist/releases/latest

If your proxy requires authentication, make sure the root user and the systemd service receive the proxy settings. A proxy configured only in your interactive shell will not automatically apply to the service.

The live count is wrong

If events are arriving but the result looks wrong:

1. Check the site selector.
2. Check the person’s recent events.
3. Check the door classification.
4. Change room-to-room doors to Internal.
5. Check whether a person left without badging out.
6. Check the connector’s daily presence reset time.

Read How presence works for the limits of badge-based presence.

What to collect before asking for help

Include:

• the workspace and site name
• the Runner name and operating system
• the time the problem happened, including time zone
• the status or error shown in Musterly
• the relevant door name
• a short extract of Runner logs with secrets removed

Never include API tokens, pairing codes, session cookies or credential-bearing URLs.