Troubleshooting

Something broke? Find the message WolfWave showed you, or the symptom, below. Each section says what happened and what to do.

Most error banners in WolfWave already have the fix button on them, and a Learn More link that lands on the matching section here.

Still stuck? Go to Settings → Advanced and click Export Logs. It saves one file with your app version, macOS version, the last crash (if any), and every log WolfWave still has. Logs never contain tokens. Attach it to a GitHub issue.

TwitchCopy Anchor Link

If your network drops, WolfWave reconnects on its own. It retries fast at first, then about once a minute. Waking your Mac starts the fast retries again.

Chat commands don't replyCopy Anchor Link

Check these in order:

1. Is Twitch connected? Settings → Twitch should show your channel.
2. Is the command on? Most commands start off. See Turn commands on.
3. For !sr: is Song Requests on? Settings → Song Requests → Enable Song Requests.
4. Is "Only reply while live" on? Settings → Twitch → Chat commands. If it is, commands stay quiet until you go live.
5. Cooldown? A command waits a few seconds between uses. Mods and you skip cooldowns, so test from a viewer account to see what viewers see.
6. First word? The command must start the message. hey !song won't work.

Sign-in expiredCopy Anchor Link

Message: "Twitch sign-in expired."

Why: WolfWave refreshes your sign-in in the background. That can fail if you removed WolfWave's access on Twitch, changed your Twitch password, or didn't use it for a long time.

Fix: Click Reconnect with Twitch. Your channel, commands, and settings stay as they were.

That code expiredCopy Anchor Link

Message: "That code expired."

Why: Twitch sign-in codes only last a few minutes. The code on screen shows how long it has left.

Fix: Click Get a new code and approve it on Twitch.

Couldn't sign out of TwitchCopy Anchor Link

Message: "Couldn't sign out of Twitch" or "Couldn't switch Twitch accounts."

Why: WolfWave couldn't disconnect from Twitch first. You're still signed in, and nothing was removed.

Fix: Click Try Again. If the message says macOS wouldn't remove the saved sign-in, see Couldn't save your Twitch sign-in.

"Your sign-in is fine"Copy Anchor Link

Why: Your sign-in works. Twitch refused one request for another reason. Reconnecting won't help.

No Twitch channel by that nameCopy Anchor Link

Message: "No Twitch channel by that name."

Why: Usually a typo.

Fix: Use the name from your channel's web address, not your display name. If your page is twitch.tv/graywolf, the channel is graywolf.

• Letters, numbers, and underscores only.
• 25 characters or fewer.

Missing a Twitch permissionCopy Anchor Link

Why: Your sign-in works, but it's missing a permission a feature needs. This happens when you turn on a feature after you first signed in.

Fix: Click Reconnect with Twitch. This is the one time reconnecting a working sign-in is right: a background refresh can't add a permission you never gave. Everything else keeps working until you do.

Channel points and Bits also need:

• The tool enabled in Twitch's Creator Dashboard, plus Twitch API access for the feature. Twitch's third-party API restrictions can differ from dashboard access; follow the setup error shown in WolfWave.
• Your broadcaster account. A separate bot account can't manage your channel's rewards.

WolfWave isn't set up for TwitchCopy Anchor Link

Message: "WolfWave isn't set up for Twitch."

Why: This copy of WolfWave was built without a Twitch Client ID. You only see this if you built WolfWave yourself.

Fix: Download WolfWave, or set TWITCH_CLIENT_ID in apps/native/WolfWave/Config.xcconfig and rebuild. See Development.

Commands stopped replying, but Twitch looks connectedCopy Anchor Link

Why: WolfWave can read chat, but Twitch is refusing the messages it sends.

Fix:

1. Reconnect Twitch.
2. If it happens again, check whether the account WolfWave signed in with is banned or timed out in your channel. This happens to bot accounts.

Apple MusicCopy Anchor Link

WolfWave notices song changes right away, and checks again every 5 seconds as a backup.

Let WolfWave read what's playingCopy Anchor Link

Message: "Let WolfWave read what's playing."

Why: macOS asks before one app can control another. WolfWave needs this Automation permission to read the current song. It also uses it to play song requests and the menu bar's playback buttons.

Fix:

1. Click Open System Settings.
2. Go to Privacy & Security → Automation → WolfWave.
3. Turn on Music.

Still says off? Quit and reopen WolfWave. macOS sometimes doesn't pass a new permission to an app that's already running.

The now-playing song is stuckCopy Anchor Link

Why: Music stopped answering WolfWave, so the card shows the last song it saw. Usually Music itself is stuck.

Fix: Quit and reopen Music. WolfWave picks the song back up on its own.

Music can't see your requests playlistCopy Anchor Link

Message: "Music can't see WolfWave Requests yet" (setup) or "Music on this Mac can't see your WolfWave Requests playlist" (Settings → Song Requests).

Why: Requests are added to your Apple Music library online, then played from the Music app on this Mac. If Sync Library is off, the Music app never sees them. WolfWave waits about 40 seconds for iCloud to sync before it shows this, so a brand-new playlist doesn't trip it.

Fix:

1. In Music, open Settings → General.
2. Turn on Sync Library.
3. In WolfWave, click Check Again. It waits for sync again before it answers.

Artwork or song links are missingCopy Anchor Link

Why: WolfWave looks up artwork and links by song title and artist. A failed lookup waits at least a minute before it tries again, longer after repeated failures.

Fix: Usually nothing. It fills in on a later song. Restarting WolfWave clears the wait.

DiscordCopy Anchor Link

Discord updates are combined and sent at most about once every 4 seconds, so a fast skip shows the final song, not every song in between.

Discord isn't connectingCopy Anchor Link

WolfWave tells you which of three problems it is:

You need the Discord desktop app. Discord in a web browser can't show WolfWave's status.

Not configuredCopy Anchor Link

Why: This copy of WolfWave was built without a Discord Application ID. Like the Twitch one, you only see this on a build you made yourself.

Fix: Download WolfWave, or set DISCORD_CLIENT_ID in Config.xcconfig and rebuild.

Stream widgets (OBS overlay)Copy Anchor Link

The overlay stopped updatingCopy Anchor Link

Why: Almost always the port or the overlay token changed, and OBS still has the old address.

Fix:

1. Open Settings → Stream Widgets.
2. Copy the address again.
3. Paste it into your OBS browser source.

Making a new token breaks every address that used the old one. That's on purpose.

Port already in useCopy Anchor Link

Message: "Couldn't start" on Stream Widgets. The Stream Deck pane shows Server error.

Why: Another app on your Mac is already using that port. WolfWave retries up to 5 times before it gives up.

Fix:

1. Turn Stream Widgets off. (The port field is locked while it's on.)
2. Pick a different port.
3. Turn Stream Widgets back on.
4. Update the address in OBS to the new port.

An invalid port isn't saved. The field says "Not saved" and keeps your old port.

That token won't saveCopy Anchor Link

Why: A token must be exactly 64 characters, using only 0–9 and a–f. The overlay token and the Stream Deck control token must also be different.

If saving fails, your current token stays active, so OBS keeps working.

Stream DeckCopy Anchor Link

The plugin shows what's wrong right on the keys.

Every key says OfflineCopy Anchor Link

Why: One of these:

• WolfWave isn't running.
• The Stream Widgets server is off or couldn't start. The Stream Deck pane says Server off, Server error, or Starting.
• WolfWave rejected the token.

Fix:

1. Open WolfWave.
2. Turn on the server in Settings → Stream Widgets. Stream Deck uses the same server, even if you don't use the overlay.
3. If the plugin's panel says "WolfWave rejected this token", copy Stream Deck Control Token again from Settings → Stream Deck and paste it into the plugin. The token changes when you make a new one, and the overlay token won't work here.

Every key says Token?Copy Anchor Link

Why: The plugin has no control token, or it isn't 64 characters.

Fix: Copy Stream Deck Control Token from Settings → Stream Deck. Paste it into any one key's settings in the Stream Deck app. Every key shares it.

The panel says Token format is valid when the shape is right, and Connected once WolfWave accepts it.

Every key says UpdateCopy Anchor Link

Why: WolfWave and the plugin speak different versions. WolfWave 2.2.0 uses protocol version 3. The panel says "Update the plugin."

Fix: Update WolfWave, install the current plugin, then reload it in the Stream Deck app. Setup steps: Stream Deck.

Settings and dataCopy Anchor Link

Reset stoppedCopy Anchor Link

Message: "Reset stopped" or "Reset stopped partway."

Erase & Reset first disconnects Twitch, then removes your saved sign-ins, then clears everything else. The message tells you how far it got:

• "…so nothing was erased." Twitch couldn't disconnect, or the saved sign-ins couldn't be removed. Click Try Again. If it keeps failing, restart your Mac and retry.
• "…your history and logs couldn't be erased." Your settings and sign-ins are already gone. Relaunch WolfWave to finish.

That backup file won't importCopy Anchor Link

Why: One of these:

• The file isn't a WolfWave backup, or it's damaged.
• It was made by a newer WolfWave than yours. Update WolfWave first.

Backups come from Settings → Advanced → Export Settings. See Backup.

Couldn't save your Twitch sign-inCopy Anchor Link

Message: "Couldn't save your Twitch sign-in" (or "Couldn't sign out of Twitch" when removing it fails).

Why: macOS blocked WolfWave from using the Keychain, where your sign-in is stored.

Fix:

1. Sign in again (or click Try Again to sign out).
2. If it happens every launch, open Keychain Access and check whether your login keychain is locked.
3. Still failing? Restart your Mac.

UpdatesCopy Anchor Link

Update check failsCopy Anchor Link

Why: WolfWave couldn't reach the update server. Usually a short network problem.

Fix: Try again from the menu bar: Help → Check for Updates…, or Settings → Software Update.

Installed with Homebrew? WolfWave doesn't update itself. Run:

brew upgrade wolfwave

Still stuckCopy Anchor Link

1. Settings → Advanced → Export Logs.
2. Open an issue and attach the file.
3. Say what you were doing and the exact message WolfWave showed.

Or ask in the Discord community.