Troubleshooting
Work out which step is failing, then fix that one.
Start by finding out how far the event gets. How events flow has the full path; this table is the short version.
| What you see | Where to look |
|---|---|
| Event log empty on a busy stream | TikTok will not connect |
| Events arrive, Triggers Fired stays put | Nothing triggers |
| Triggers Fired moves, model does not | VTube Studio will not connect |
| Nothing throws | Nothing throws |
| OBS source is blank | OBS shows nothing |
VTube Studio will not connect
Check the plugin API is on. In VTube Studio, Start API (allow plugins) has to be switched on, on port 8001.
Look for the approval prompt. VTube Studio asks you to allow the plugin the first time, and the prompt only appears in the VTube Studio window. Vfinity sits at Connecting until you answer it. Bring VTube Studio to the front.
Check the status word. Connected is not enough. Actions only work at Authenticated.
It connects then drops. VTube Studio was closed or restarted. Vfinity retries and shows a countdown to the next attempt.
The hotkey list is empty. Vfinity is connected, but the loaded model has no hotkeys. Create one in VTube Studio.
Full setup: Connect VTube Studio.
TikTok LIVE will not connect
You have to be live. There is no room to read otherwise, and the connection fails immediately.
Drop the @. The username field takes soursama_, not @soursama_.
The account has to be public. A private account has no readable LIVE room.
"No username set" on the Dashboard card means the field is empty.
Custom mode with nothing running. If Connection Type is Custom WebSocket, Vfinity connects to a connector you run. If TikFinity is closed, nothing arrives. Switch to Built-in bridge (Vfinity) if you did not mean to be in custom mode.
Full setup: Connect TikTok LIVE.
Events arrive but nothing triggers
The event log fills, Triggers Fired does not move. The rule is not matching.
The gift name was typed, not picked. Open the mapping and use Pick instead. Picking stores the gift's numeric id; typing relies on a name match that breaks across regions.
A threshold is not met. Minimum gifts, Minimum likes and Minimum count all have to be reached before the action runs.
The rate limit is holding it. Max Triggers and Time Window cap how often the rule may fire.
Count mode is per viewer. A "10 roses" threshold with Count per viewer needs one viewer to send all ten.
The mapping is off. Check the toggle on its row.
A chat trigger is not matching. Exact needs the whole message. Use Starts with for commands, and check the case-sensitivity toggle.
Test with the Event Simulator on the Dashboard rather than waiting for a real viewer.
Triggers fire but the model does nothing
Triggers Fired counts matches, not results. If it moves and nothing happens:
- VTube Studio is not Authenticated. Check the VTS pill.
- The hotkey exists but does nothing for this model. Test it inside VTube Studio.
- A VFX Preset Name does not match a preset in VTube Studio exactly.
- A Move Model action ran, and the model is now somewhere unexpected because Return to original position is off.
Nothing throws
Read the Needs attention panel at the top of the Throwing tab first. It lists every reason nothing is throwing, each with a Fix button.
The ones that catch people out:
The scene is off. Enabled at the top right of the Throwing tab is off on a fresh install.
A diamond minimum is blocking everything. Minimum diamonds to throw applies to gift mappings as well as auto-thrown gifts. Most gifts are 1 to 10 diamonds, so a minimum of 50 blocks nearly all of them.
Only mapped gifts throw. With gift mappings present and Throw unmapped gifts too off, anything not in the list is ignored.
No OBS source is receiving. Throws are happening; nobody can see them. Add the browser source.
A gift aims at a deleted body part. It falls back to the whole model.
Full guide: Tune throwing.
OBS shows a blank source
The widget is off in Vfinity. A widget that is not enabled serves an empty page.
The port is not 21424. If the port was busy at launch, Vfinity picked another one. The Dashboard and the widget cards always show the live URL. Copy it again.
Vfinity is closed. The overlay server is part of the app.
The URL got mangled. A hand-edited URL like #overlay-goal?id=1?lang=en parses the id as 1?lang=en and renders nothing. Copy the URL from the card.
Zero width or height on the browser source.
"Shutdown source when not visible" is ticked. The widget reloads on every scene change and loses whatever it had. Clear it.
The throwing overlay is behind the model
Move the browser source above your VTube Studio capture in the OBS scene list.
Windows will not open the installer
SmartScreen: click More info, then Run anyway. Vfinity is not code-signed. See Privacy and safety.
macOS will not open the app
Right-click the app and choose Open rather than double-clicking. You only need to do this once.
Reading the logs
Turn on Verbose logging in SettingsPreferences and data, then open the debug console with the >_ button in the title bar. Verbose mode records raw WebSocket frames as well as errors.
Errors and warnings are always recorded, whether verbose is on or not.
Still stuck
Ask in the Discord server. The changelog in the app has the same invite. Include your operating system, the Vfinity version from the title bar, and what the debug console says.