Troubleshooting
Something not working? Find what you're seeing below. Most problems have a quick fix.
| What you see | Likely reason | What to do |
|---|---|---|
| Bubbles stopped showing after a new look | The Custom CSS in OBS is hiding them | In OBS, open the BubbleFacts source's properties, empty the Custom CSS box and click OK. The look you picked under Settings, Bubbles comes back. |
| Mac says "BubbleFacts" Not Opened, or that Apple can't check it | The app isn't signed yet | Open System Settings, then Privacy & Security, scroll down and click Open Anyway. On older Macs, right-click the app, choose Open, then Open again. |
| On Linux, BubbleFacts stays on "Getting BubbleFacts ready" | A bug in versions 2.0.0 to 2.1.0 of BubbleFacts on Linux | Download 2.1.1 or newer from the download page and install it over the old one. Your settings are kept. |
| Windows says "Windows protected your PC" | The app isn't signed yet | Click More info, then Run anyway. |
| A small red dot in the bottom-right corner | The overlay can't reach the app | Open BubbleFacts. If it's already open, check the Stream light on the dashboard, or quit it from the menu bar or tray and open it again. |
| Nothing at all, not even a red dot | OBS isn't loading the overlay | First click Show a test bubble. If it appears, OBS is fine: that song just had no reliable facts, and the dashboard says so. If it doesn't, check the source is visible (the eye icon in Sources). Then drag the tile from BubbleFacts into OBS again. If you added it by hand, check it uses Local file and points at the file shown under Help and troubleshooting. |
| The dashboard says "Connecting to OBS", then "Add BubbleFacts to OBS" | BubbleFacts just started and OBS hasn't picked it up yet, or OBS doesn't have it | If BubbleFacts is already in OBS, wait a few seconds. If it still asks you to add it, check OBS is open and the BubbleFacts source is in the current scene, or drag the tile into OBS again. |
| No test bubble, and no "It's on your stream!" | OBS didn't load the overlay, or BubbleFacts runs on a different computer | BubbleFacts needs to run on the same computer as OBS. Try dragging the tile again, or add it by hand. |
| "Your StreamerSongList sign-in ended" or "StreamerSongList didn't accept your sign-in" | Your sign-in ran out, or the token is wrong or expired | Click Sign in in the app's message. Using a token? Click Open Settings, open Use a token instead and paste a new token (see Having trouble signing in?). |
| "StreamerSongList isn't answering right now. Your sign-in is fine" | StreamerSongList is down or slow for a while | Nothing to do. BubbleFacts keeps trying and carries on by itself when StreamerSongList answers again. You don't need to sign in again. |
| The app says StreamElements didn't accept your JWT token | The token was reset or pasted wrong | Get the token again (see Use StreamElements instead) and paste it in Settings, under Your song list. Then click Save. |
| "Reconnecting to StreamElements" while a song plays | StreamElements says a song is playing, but BubbleFacts can't see which one | Nothing, usually. If it lasts about two more minutes, BubbleFacts restarts its connection on its own. Your song queue isn't touched. |
| No bubbles, though a song is playing | BubbleFacts doesn't see the song. Your queue has none marked as playing, the request player has stopped, or the now playing file is empty, the wrong file, or hasn't changed in 15 minutes | Start the song the way you usually do and watch the Songs light on the dashboard: it says Following when BubbleFacts sees it. With a now playing file, open Settings, then Your song list, and check that the folder or file shown is the one your music app writes to. |
| Nightbot is chosen, but no song shows | Nightbot's desktop app writes the song file, and it isn't running or hasn't written a song yet | Open Nightbot's desktop app and play a song. BubbleFacts reads the newest .txt file in Documents/Nightbot, so it sees nothing while the app is closed. See Follow a now playing file instead. |
| Bubbles start a bit after a song changes in StreamerSongList | The live connection to StreamerSongList dropped, so BubbleFacts is checking your list every 15 seconds instead | Look under Songs on the dashboard. Checking your list every 15 seconds still works, just a little later; it goes back to Hearing your queue live on its own. If it keeps happening, click Report a problem and add your logs (see How do I send my logs?). |
| OBS reloads the BubbleFacts source in the middle of a song, after a scene switch or with a second output | OBS loads the overlay page again | Nothing. Within a few seconds, the rest of that song's bubbles come back, and the ones viewers already saw aren't repeated. A bubble that was showing returns for the time it had left. The credit bubble doesn't come back. |
| The app says "The AI download paused" | Not enough disk space, the connection dropped, or the file didn't match the one BubbleFacts expects | If the connection dropped, the app tries again on its own. If you're low on space, free up at least 4 GB. If the file didn't match, click Try again later; if it keeps happening, ask in #help on the Discord. |
| No facts about the song, or none at all | No source knew the song | BubbleFacts reads your whole song list once to learn how you write it: the game in the artist field, or "Game - Track" with the composer as artist, or "Track (Film)", and so on. If a song still gets the wrong match, the surest form is the game's name in the artist field. With StreamElements, clearly titled videos ("Artist - Song") work best. A classical piece is found by its catalog number or nickname ("Nocturne Op. 9 No. 2"), with its composer or performer as the artist. An artist of "Traditional" or "Anon." is looked up by the title alone. Obscure songs often have no article, so they get custom facts instead, or none until you add your own. |
| Few or no facts, soon after installing | BubbleFacts is still getting ready | Until it's ready, songs get facts from music databases and your own facts. The Facts light on the dashboard shows the progress. |
| Fewer bubbles than expected | Some captions failed the fact check, your computer was busy, or your custom facts are waiting their turn | Usually nothing. Short articles give fewer captions, which means the check is working. If the dashboard says Your computer is busy, so fewer facts, BubbleFacts goes back to normal on its own once songs get their facts on time (see Check that it works). A custom fact that showed in the last hour waits; five or more keep the bubbles full. |
| Bubbles come late, and the dashboard says "Facts took" a long time | The built-in AI is sharing your computer with the stream | Turn on Prepare my songs in Settings, so facts are written while you're not streaming and show as soon as a song starts. |
| Your songs says "Waiting" | Prepare my songs works only while OBS is closed, your computer is plugged in, and the AI on this computer is chosen and ready | Do what the line says: close OBS, or plug your computer in. "BubbleFacts is on your stream in OBS" with OBS closed means a browser tab from Test in your browser is still open: close it. "BubbleFacts can't tell right now whether OBS is open" means it couldn't read the list of running programs; it checks again by itself, so just wait. The same goes for "can't tell right now whether this computer is plugged in". With an online AI chosen, songs aren't prepared. |
| Bubbles cover your camera, or jump around the screen | Bubbles move between several spots, to keep them from covering each other | Open Settings, then Bubbles, and set Where bubbles appear to one spot, like Top right or Bottom center. Every bubble then shows there, each one replacing the last. Or choose the top, bottom, left or right to keep them away from your camera. |
| The banner is cut off, or the bubbles sit in the wrong place | The source isn't the size of your canvas | Remove the source and drag the tile from BubbleFacts into OBS again. Or right-click the source, choose Properties, and set Width and Height to your canvas size (see adding it by hand). |
| The source is blank, or stops updating | An OBS Browser source setting, or an old copy of the page | Right-click the source, choose Properties, and click Refresh cache of current page. Leave Shutdown source when not visible and Refresh browser when scene becomes active off, and don't clear the Custom CSS that OBS fills in. |
| Settings says another app is already using the Hands-free Wrong key | Another app on this computer listens for the same key | Choose another key under Settings, then Bubbles, then Hands-free Wrong, and set your foot pedal or Stream Deck to send it. F13 is the least likely to clash. |
| Viewers on phones say the bubbles are small | Phone screens are small | In Settings, then Bubbles, set Bubble size to Large or Larger. |
| Your Mac asks for permission every time BubbleFacts opens | Allow was clicked, which covers one time only | Click Always Allow the next time it asks. It asks once after each update. |
| You need the bubbles off the screen right now | Anything | Click Pause bubbles on the dashboard, or in the menu bar or tray menu. |
| Your stream stutters when a song starts | The built-in AI is sharing your computer with OBS | BubbleFacts already slows its AI down while a game or OBS keeps the processor nearly full. If it still stutters, turn on Prepare my songs, so facts are written while you're not streaming. |
| The app says the built-in AI can't run on this computer | The processor or graphics can't run it, even in processor-only mode | Nothing to do on stream: songs still get facts from music databases and your own facts. See the system requirements. |
| A new version has a problem and you want the one before | Something changed that you rely on | Quit BubbleFacts, download the earlier version from the list of all versions, and install it over the new one. Your settings and facts work with it; a setting the earlier version doesn't have is just left out. Then please tell us what went wrong in #help. |
| You're moving to a new computer | Your settings and facts are on the old one | On the old computer, open Settings, then Advanced, and click Back up…. Install BubbleFacts on the new one, sign in, then use Restore… in the same place and pick that file. Your sign-in and keys aren't in the backup, so you sign in again. The new computer starts on BubbleFacts' own AI: online AIs and Ollama aren't offered any more. If you used Prepare my songs, turn it on again there: it prepares your songs again on the new computer. |
Still stuck? In the app, open Help and troubleshooting and click Report a problem (or Copy report to paste it somewhere yourself), or ask in #help on the Discord. The help page lists every option.