Troubleshooting

The first launch is blocked

"MacroSIP cannot be opened because the developer cannot be verified": the app is signed ad hoc, not notarized. Right-click MacroSIP in Applications and choose Open, or run xattr -dr com.apple.quarantine /Applications/MacroSIP.app once. Details in Installation. Updates installed by the app itself open without this dialog.

Nobody hears me: microphone permission

The call panel shows "Microphone access is off" with Open System Settings. Allow MacroSIP under System Settings › Privacy & Security › Microphone. Because of the ad hoc signature macOS asks again after every update; allow it once more on the first call after updating. Then check the level meter in Settings › Audio while speaking.

The account shows "403" or "401"

Status	Meaning	What to do
401 Unauthorized, 403 Forbidden	The server rejected the credentials. Settings › Accounts shows "REGISTER rejected at 14:52. Check the username and password."	Check Username, Password and, if your PBX uses a separate authentication name, Auth username in the Advanced group. Press Test in the editor: "Registered successfully (120 ms)" confirms the fix.
"No response" (Test) or "Office · retry in 8 s"	No answer from the server.	Check the server name and port, the Transport (UDP, TCP or TLS; the PBX must listen on the one you chose) and firewalls. The engine retries with backoff.
"Registering…" that never ends	Packets leave but no answer comes back.	Same as above; try another transport, or set a STUN server.

See Accounts for every status.

TLS certificate errors

With Transport: TLS the engine verifies the server certificate against the system root certificates. A certificate that does not match the host, is expired or is self-signed fails the registration permanently (no retry) with a TLS reason in the status and the log. Fix the certificate on the server, or, for a self-signed one you trust, turn off Verify server certificate in the Advanced group of the editor ("Turn off only for a server with a self-signed certificate.").

No audio or one-way audio

Usually NAT or a firewall between you and the PBX. Set a STUN server, keep Use ICE and Use rport on, allow UDP on the local SIP port and the RTP port range, and check the devices in Settings › Audio. The full checklist is in Audio.

Calls drop when the network changes

The engine re-registers at once on a network change or wake and sends a re-INVITE so calls survive an IP change; the call panel shows "Reconnecting… 12 s" meanwhile and the status bar "Office · retry in 8 s". If the media does not return within 60 s the call ends with "Connection lost" in the call log. If drops persist, lower Keep-alive interval in Settings › Network.

Headset buttons do nothing

MacroSIP reads the HID telephony controls of USB headsets (hook, flash, hold, mute, redial). Check that Headset buttons in Settings › Audio is on and that the row names your device ("Connected: Jabra Evolve2 65"); "No headset with call controls" means no connected device exposes telephony controls. The log file has the line "headset buttons: connected, …" when a device is picked up, and "headset buttons: cannot open …" when macOS refused to open it; that can be a matter of the Input Monitoring permission (System Settings › Privacy & Security). Bluetooth headsets whose buttons work through the hands-free profile are handled by macOS and are not supported. The headset auto-switch in the same pane is a separate feature and does not need the buttons.

The caller hears no hold music

Check Source in Settings › Audio › Hold music: Off sends silence. Many PBXs replace what a phone sends on hold with their own music, so the caller hears the server's music instead of MacroSIP's; that is a server setting. A file the engine could not read keeps the previous source and the group footer names the reason ("The file could not be used: …"). You never hear the hold music yourself.

The ringtone is not the one I chose

Open Settings › Audio › Ringtone and press Play. The preview plays the real choice at the chosen volume, so what you hear is what an incoming call will ring with. Classic, Digital and Soft are three different melodies.
If the popup shows your own file ("Custom: office-bell.m4a") but the old sound plays, look under the group for "The ringtone file could not be used: …". A file that cannot be read (damaged, protected, or a format macOS cannot open) keeps the previous choice. Use a WAV, AIFF, M4A or MP3 file.
No sound at all: check Volume (0 is silent) and Ringtone device; it is the output for the ring only and may point at a headset or another speaker.
Before 26.3 the chosen melody was used by the preview only and calls always rang with the default one. Update to 26.3.0 or newer (Installation).

See Audio.

A message shows Sent but the phone did not get it

Sent only means that the SIP server (or the other party) accepted the message. It does not say that a phone received it: delivery to a mobile depends on the server and what is behind it (for SMS through Asterisk chan_dongle: the modem, the SIM and the carrier). Check the server's log. A message that was not accepted shows Not sent with the reason and Retry instead. See Messages.

If there is no Messages tab at all, messages are off: switch on Text messages (SIP MESSAGE) in Settings › General.

Caller names are wrong or missing

The name comes from the SIP display name, then from a contact matching any of its numbers, then from a directory source asked for at most one second. Add the number to a contact, or add a directory source (Directory).

Directory and LDAP errors

Text	Meaning
"Cannot connect to ldap.example.com"	Host unreachable or wrong port;
"Timed out"	No answer in 3 s (30 s for an import).
"Invalid bind DN or password"	The simple bind was refused. Leave Bind DN empty for anonymous search.
"The server must be ldap://host or ldaps://host"	The Server field has no scheme.
"Enter an http, https or file URL", "HTTP 404"	URL source unreachable or wrong.
"No number column in the header", "The file is not text"	CSV without a recognised number column, or not a text file.
"The file is not valid JSON", "No array of contacts in the JSON"	JSON source malformed.
"Access denied", "Contacts access has not been requested"	macOS Contacts permission; allow MacroSIP in System Settings › Privacy & Security › Contacts.
"Sign in required"	Google Contacts without a valid token (not signed in yet, or access revoked). Select the source in Settings › Directory and press Sign In…; the browser opens Google's consent page.
"Google sign-in is not configured in this build"	The build has no Google client id, so Google Contacts cannot be signed in; the other source types work. Install a build that is configured for Google sign-in.

A library message that MacroSIP cannot translate (an LDAP diagnostic) is shown as it is. A failed source is skipped for 60 s and then retried.

The log file and Copy Diagnostics

MacroSIP writes ~/Library/Logs/MacroSIP/MacroSIP.log (2 MB per file, 3 files kept). Settings › General › Advanced › Open Log Folder reveals it in Finder; Copy Diagnostics copies versions, macOS, accounts without passwords and settings to the clipboard ("Diagnostics copied to the clipboard."). For a deeper SIP trace start the app with open /Applications/MacroSIP.app --args --log-level 5 (0–6). The app also logs to the unified log under the subsystem com.hsmm.macrosip.

Debug mode and the diagnostics archive

Debug mode writes much more detail to the log, including SIP messages. Turn it on when a problem needs a closer look, then send the developers an archive:

Open Settings › General › Advanced › Troubleshooting and switch on Debug mode. It takes effect at once, without a restart, and stays on across launches until you switch it off. The log files then grow to 8 MB each, with 3 files kept. If MacroSIP was started with --log-level or MACROSIP_LOG_LEVEL, that level wins: the switch is disabled and shows the level it was started with.
Reproduce the problem: make the call, or try the registration, that fails.
Click Create Archive… in the same group and choose where to save the ZIP. The default name is MacroSIP-diagnostics-YYYYMMDD-HHmm.zip, on the Desktop. When the archive is saved, MacroSIP shows it in Finder with the banner "Diagnostics archive saved: …".
Send the ZIP with your issue report, as described in Reporting an issue below. Send it only to someone you trust.
Switch Debug mode off. Until you do, the log keeps growing.

The archive contains:

logs/: all the log files, including the rotated ones;
diagnostics.txt: the diagnostics report (versions, accounts, settings and log level);
crash-reports/: MacroSIP crash reports from the last 30 days, at most 5, included as they are.

Phone numbers and server addresses stay in the archive. Passwords and authentication values are removed from the copies: digest response, nonce, cnonce and opaque values, Basic and Bearer credentials, and passwords in URLs are replaced with <redacted>. The log files on your Mac are not changed.

Where settings and contacts are stored

What	Where
Accounts (without passwords), contacts, call log, settings, quick keys	`~/Library/Application Support/MacroSIP/` as `accounts.json`, `contacts.json`, `calllog.json`, `settings.json`; photos in `photos/`. Written atomically; a damaged file is set aside as `<name>.broken-<date>.json` or `contacts.damaged-<date>.json` and the app starts with what it could read.
Passwords (SIP accounts, LDAP bind)	Login Keychain, service `com.hsmm.macrosip`, one item per account id. Deleting an account removes its item.
Recordings	`~/Music/MacroSIP Recordings` or the folder chosen in Settings › Recording.
Log	`~/Library/Logs/MacroSIP/`.

To move to another Mac copy the Application Support folder and re-enter the passwords.

Reporting an issue

Open an issue at github.com/HSMM/MacroSIP/issues with:

The MacroSIP version (MacroSIP › About) and macOS version.
The output of Copy Diagnostics (it contains no passwords).
What you did, what you expected, what happened, and the time, so the matching lines in MacroSIP.log can be found. Attach the log for call or registration failures, with anything private removed.
The PBX or provider type (Asterisk, FreePBX, 3CX, …) if you know it.

Feature requests go to the same place; the plan is in the roadmap.