Troubleshooting

The most common problems, roughly in the order people hit them. If yours isn’t here, getting help at the bottom shows how to send us what we need to fix it.

When sign-in fails, the app explains what went wrong in plain language — and Show technical details reveals the raw error if you want it. The usual causes:

“Didn’t recognize the username or password.” Double-check both against what your provider listed. Two classic traps: providers usually have a separate SIP password distinct from your website login, and the username is often your full phone number in international format (a stripped leading + is enough to fail).
“Couldn’t find your provider’s server.” The domain is misspelled, or it’s a website address rather than a SIP domain — it should look like sip.example.com. On Twilio specifically, the domain is your own SIP Domain (yourname.sip.twilio.com), not the generic host — see the Twilio guide.
“Didn’t answer in time.” Check your internet connection and try again. If it keeps timing out, your provider may be having issues, or a firewall is blocking the connection.
“Server refused the connection.” The port or connection type is probably wrong. Most providers use port 5060 with UDP — check the Advanced section of the account against your provider’s documentation.

The provider guides list per-provider gotchas, and Picking a SIP provider covers the generic failure modes in more depth.

Microphone doesn’t work

If callers can’t hear you, or the mic test stays silent:

macOS: the most likely cause is denied permission. Open System Settings → Privacy & Security → Microphone and make sure WaveKat Voice is allowed, then try again. (macOS only asks once — if you clicked Don’t Allow the first time, this is the fix.)
Re-run the mic test from the welcome guide (Welcome guide in the sidebar → the Test call step → Test microphone) to confirm: it records a few seconds and plays them back.
If you use a headset or external microphone, check it’s plugged in and selected as your system’s input device.

No incoming calls, but outgoing works

This is almost always provider-side routing: your number isn’t pointed at this sign-in. Some providers require you to explicitly map a number to the trunk or device in their dashboard — see Common failure modes and your provider’s guide (Twilio, 2talk).

Linux

The AppImage won’t start. It needs FUSE: sudo apt install libfuse2t64 on Ubuntu 24.04, sudo apt install libfuse2 on older releases. (The .deb build doesn’t need this — see Installing.)
The AppImage never updates. It can only update itself when it lives somewhere writable. Move it out of any read-only or system location — your home folder is fine.
The app keeps running after I close it. Closing the window keeps WaveKat Voice in the background so you can still receive calls — that’s intentional. To quit completely, click the tray icon (in your top bar’s status area) and choose Quit.

Calls drop after a few minutes

Usually a router timing out the connection (NAT). Open the account’s Advanced section and set Keep-alive to 60; if that doesn’t help, switch Connection to TCP — some routers handle long-lived TCP connections better. The 2talk guide has a worked example.

Getting help

When you’re stuck, open Settings → About:

Copy system info copies your version, build, and OS details — paste it into your message so we can reproduce the problem.
Report a bug opens a pre-filled email with that info already included.
Open log file (the small link at the bottom) opens the app’s log — only needed if we ask for it.

Or just email hello@wavekat.com and describe what happened. We read every report.