Skip to content

Troubleshooting

Find what you see, then work down the causes, most likely first. Each fix says what to click. If your problem isn't here, the Activity page is the best place to look next: every failed step and every warning CroStream raises appears there, in words, with the reason.

Two places that explain most problems

  • The status bar at the bottom of the window: every connection's status. Hover one for its full detail or error. See What the status means.
  • Activity (or History, filtered to errors): what failed, when, and why. On the Dashboard, a failed run in the last hour shows as "Something failed in the last hour" with See what went wrong.

Starting CroStream

"CroStream is already running on this computer"

Cause Fix
CroStream is already open, maybe hidden in the tray. Opening CroStream again normally brings the running window to the front. If you see this message instead, look for the CroStream icon in the tray (menu bar on macOS) and choose Show CroStream, or quit it from there with Quit CroStream.
Browser mode and the desktop app are both trying to run. Only one copy can use your settings at a time. Close one of them.
The other copy just crashed or is still closing. Wait a few seconds and try again. The lock is released when the other copy ends, even after a crash. There's no need to delete any file.

streamlink, CroStream's earlier name, is still running, so CroStream can't take over its folder. Quit streamlink (check its tray icon), then start CroStream. See Upgrading.

My triggers and macros are gone after starting

Cause Fix
The settings file is damaged (for example after editing it by hand). CroStream then runs on default settings and says why on the Activity page. Fix the file, or restore an automatic copy: Settings → Backups → Restore. See Backups.
You started an older version after a newer one. An older version can't read a newer settings file. Start the newer version again. To really go back, see Rolling back.
CroStream is using a different folder (for example a copy started with a custom folder). Check the path under Settings → Config folder. See Where files are kept.

Twitch

Twitch keeps asking me to log in

Cause Fix
The login expired. Twitch logins from CroStream last a limited time and can't be renewed in the background. Click Login on the Twitch page. This is normal every couple of months; see How long a login lasts.
You removed CroStream's access on twitch.tv (Settings → Connections), so Twitch rejects the login. Log in again and approve.
The login never finished: the browser page said "invalid or was already used", "declined" or "could not reach CroStream". Start again from CroStream with Login. Each login link works once; see Twitch troubleshooting.
Another program is using port 62689, which the login needs. The Activity page shows "login server unavailable … (is another CroStream running?)". Close the other program (often a second CroStream, such as browser mode), then restart CroStream.
You're using browser mode from another computer, so the login can't get back to CroStream. Forward port 62689 over SSH first. See Logging in on a computer without a screen.

Some Twitch triggers never fire

Cause Fix
Your login lacks a permission the event needs. The Activity page says "log in to Twitch again to enable: …", and the trigger is flagged. Click Log in again on the Twitch page. See Missing permissions.
The event is for Affiliate and Partner channels only (channel points, polls, predictions). See Affiliate and Partner features.
The trigger is turned off, or its role or cooldown keeps it from firing. Open the trigger in Triggers and check Minimum role, Cooldown and User cooldown. See Triggers.
Twitch isn't connected. Check the status bar. See Integrations.

OBS

OBS won't connect

The status stays on Connecting and shows an error.

Cause Fix
OBS isn't running, or its WebSocket server is off. Start OBS. In OBS, open Tools → WebSocket Server Settings and tick Enable WebSocket server.
The password is wrong (an authentication error). Copy the Server Password from Show Connect Info in OBS, paste it on the OBS Studio page and click Save.
The host or port is wrong. Host is localhost for OBS on this computer; Port must match Server Port in OBS (default 4455).
OBS runs on another computer and a firewall blocks the port. Allow the port on that computer's firewall.
OBS is older than version 28. Update OBS.

If the status is Disconnected instead, CroStream isn't trying: click Connect, and turn on Connect automatically. See OBS Studio.

Clip doesn't save a replay

The OBS replay buffer isn't running ("replay buffer is not active"). Start it in OBS. See The replay buffer and clips.

Overlays

Overlays are blank in OBS

Cause Fix
CroStream isn't running. OBS loads overlays from CroStream. Start CroStream, then in OBS right-click the browser source → Properties → Refresh cache of current page.
OBS runs on another computer. Overlay addresses (http://127.0.0.1:62689/overlay/…) only work on the computer running CroStream. Run CroStream on the same computer as OBS.
The overlay address in OBS is wrong or old, or the overlay was deleted ("OBS sources using it will go blank"). On the Overlays page, open the overlay's menu and choose Copy OBS URL, then paste it into the browser source's URL. Or use Add to OBS to create the source for you.
The browser source is the wrong size, so elements are off screen. Set the source's Width and Height to the overlay's size, shown in the overlay editor under OBS browser source.
Nothing is meant to show yet: alerts stay hidden until one plays. Fire a test from the trigger's Test button and watch the source.
Port 62689 is taken, so CroStream can't serve overlays. The overlay editor shows "…" for the URL and Copy URL is greyed out. Close the other program using the port (often a second CroStream) and restart CroStream.

See Overlays.

Sounds

A sound doesn't play

Cause Fix
The sound plays In OBS: it goes out on stream, but you only hear it if OBS monitors it. That's expected. To hear it yourself, choose On this PC or Both for the alert's Sound plays, or turn on monitoring for the source in OBS.
The file was moved or deleted ("cannot open"). Pick the file again in the action, or use the media library.
The chosen Output device isn't connected (for example an unplugged headset). CroStream plays on the system default instead and warns "Output device … not found". Plug the device in, or pick another.
Four sounds are already playing ("too many sounds playing at once"). Wait for one to finish, or use a queue to pace them. Stop all sounds ends them all.
Linux: "no audio player found". Install paplay (PulseAudio), pw-play (PipeWire) or ffplay.
Play sound in OBS isn't set up. It needs an always-visible Media Source with Close file when inactive. See Play a sound through OBS.

Hotkeys

A hotkey doesn't fire

Check the trigger on the Triggers page: a hotkey that can't work shows a warning under it saying why.

Cause Fix
Another program already uses that key combination ("could not be registered: it may be in use by another program"). Choose a different combination, or free it in the other program.
The combination has no modifier. Add Ctrl, Alt, Shift or Super. Only F13–F24 and media keys work alone.
macOS: CroStream lacks the Accessibility permission. Allow CroStream in System Settings → Privacy & Security → Accessibility.
Linux on Wayland without XWayland ("global hotkeys need X11"). Global hotkeys work on X11 sessions (or with XWayland) only. Log in to an X11 session, or fire the macro another way, such as a chat command or a Dashboard button.

See Hotkeys.

Screen flash

The screen flash doesn't show

Cause Fix
The game runs in exclusive fullscreen, which hides other windows. Switch the game to borderless or windowed fullscreen.
"skipped: a flash is already showing". Only one flash shows at a time. Wait for it to end; Clear screen flash in the tray menu removes a stuck one.
"flashing the screen isn't available on this computer". On Linux, the flash needs a CroStream build that includes it, and GNOME on Wayland doesn't allow it (X11 and most other desktops do).
See Screen flash.

Notifications and the tray

I don't get desktop notifications

Cause Fix
The notification is turned off. Open Settings → Desktop app and turn on the ones you want under Notifications.
"System notifications aren't available on this computer." Your system can't show them to CroStream: on Linux, a notification service must be running; on macOS, CroStream must run as the installed app.
Your system blocks them. ("Saved, but the system isn't letting CroStream show notifications.") Allow CroStream in your system's notification settings (on macOS, System Settings → Notifications). Also check Do Not Disturb or Focus modes.
They're held back on purpose. Disconnect notices only come when Twitch or OBS stays down for a while; failure notices at most once every 30 seconds.

The warnings inside the CroStream window always show, whatever these settings say. See The desktop app.

The tray icon is missing (GNOME and some Linux desktops)

Cause Fix
Your desktop doesn't show tray icons. GNOME, for one, only shows them with an extension that adds tray (AppIndicator) support. Install and enable such an extension, then restart CroStream.
Until then, a hidden window is hard to get back. Turn off Close to the tray and Start in the tray under Settings → Desktop app. If the window is already hidden, open CroStream again from your app menu: that brings the running copy to the front.

Steam and Discord

Steam isn't detected

"Steam isn't installed on this computer", or always "Steam isn't running". Set the Steam folder on the Steam page to the folder that has steamapps inside. See Steam troubleshooting.

Discord isn't detected

"Discord isn't running" while it is. CroStream needs the Discord desktop app on the same computer, signed in, running as the same user; the browser version doesn't work. It connects within about half a minute of Discord starting. See Discord troubleshooting.

Webhooks

My webhook isn't firing

Work down the list. The webhook's page, Recent deliveries, shows what actually arrived.

Check What to do
Is the webhook On? An off webhook answers 404, as if it didn't exist. Turn it on in the list or on its page.
Does the call show under Recent deliveries? If not, it never got as far as the webhook, or was turned away before it (403, 404, 405 or 429: the sender sees these codes, CroStream doesn't log them). Check the address, the port, the method, and that the sender can reach this PC.
Is the listener running? The Listener panel says listening on port …, or no incoming webhooks turned on when none is on, or why the port can't be opened.
Is it a 401? The token or signature is wrong. See below.
A 202, but nothing happens? A webhook does nothing alone. You need an enabled trigger with the event A webhook is received for it, and a macro. The Activity page shows the run.
Is a trigger Cooldown swallowing calls? The activity feed says how long was left.

What the sender sees

Status Cause Fix
202 (or the status you set) Accepted.
400 The body doesn't read as the format you chose (JSON or form), or couldn't be read. The delivery's error says why. Set Body format to Auto, or fix what the sender posts.
401 The token or signature is missing or wrong. The answer gives no detail on purpose. Copy the token again, or Regenerate it; for HMAC check the signing key, the Signature header, and that the signature covers the exact body sent.
403 The caller isn't allowed by Accept requests from. Choose Local networks only or Open to all on the Listener panel, as the sender needs.
404 No such address, or the webhook is off. Check the address (/hook/<name>) and the On switch.
405 The method isn't one the webhook accepts. The Allow header lists them. Tick the method under Methods, or change the sender.
413 The body is larger than 1 MiB.
429 Too many calls: more than 10 at once from one sender, then one every 2 seconds, or more than 60 at once for the webhook, then two a second. Retry-After says how long to wait. Slow the sender down. Behind a tunnel on this PC all calls share one sender.
500 The reply you set isn't valid JSON once its variables are filled in. The trigger didn't fire. Use {name|json} inside JSON strings in the Reply, or leave the reply empty.

Another device can't reach my webhook

Cause Fix
The listener is on Localhost only, the default. Choose Local networks only on the Listener panel and click Apply.
You're using localhost from another device. Use the PC's network address from Addresses on the Listener panel.
The PC's firewall blocks the port. Allow the port (62690 unless you changed it) for your private network.
The caller is outside your network and the setting is Local networks only. That is what it's for: such calls get 403, even through a forwarded port. Use Open to all, with care; see Webhooks.
The port is used by another program. The panel shows the error. Pick another Port, Apply, and update the senders.

A webhook variable is empty

Open the delivery and read Problems: it says whether the path wasn't found, was null, or had the wrong kind of value. Paths are case-sensitive, and a form with JSON inside, like Ko-fi's, starts at the form field (data.amount). A variable with an If missing value is set to it silently. See JSON paths and mapping.

Send a webhook fails

The step's message says why, and the Activity page shows it.

Message Cause and fix
answered 401 Unauthorized (or 403, 404…) The server refused it. For a destination, Replace its secret; check the address and path. To carry on after an error answer, turn Fail on an error answer off.
request to … failed No answer: the host is down, the name doesn't resolve, or the Give up after time ran out. Try the Test on the destination, raise the timeout, or add Retries.
redirected to another site The address redirects to a different host, which CroStream refuses so a sign-in can't follow it. Use the final address.
destination … has no secret saved Open the destination and enter the token, key or password. A destination imported from a file arrives without its secret.
the JSON is not valid at line … In a json_raw body, put variables inside strings as "{name|json}".
… is not a number A Number field's value isn't a number once the variables are filled in. Check the field and its Body preview.
the destination no longer exists It was deleted. Choose another in the step.
the path … leads away from … The step's Address path points to another website. A path must stay on the destination's host.

Updates

Updating fails or isn't offered

Message What it means and what to do
"Couldn't check for updates: …" CroStream couldn't reach the update server. Check your internet connection and click Check now later.
"The update didn't install: …" The download failed or didn't pass its signature check, so nothing changed. Try again; if it keeps failing, download the latest version from the website.
"The update is ready but CroStream couldn't restart: …" Quit CroStream and start it again to finish.
"This is a development build, so it doesn't install updates." You're running a build made from source. Install a release from the website to get updates.
"Updates aren't set up in this build." This build can't update itself. Download releases from the website.
You're on Beta and see stable releases. Normal: the Beta channel gets stable releases too.

See Updates.

Crash reporting

I want to report a problem

Open Settings → Crash reporting → Report a problem… (or Report a problem… in the tray icon's menu, or Help on macOS), describe what went wrong and click Send. It needs crash reporting turned on: the box says so and takes you to the switch if it isn't. Why the switch can be locked on or missing is in Crash reporting.

Still stuck?