VTube Studio troubleshooting¶
When a VTube Studio step fails, the Activity
page shows it as vtubestudio: <action>: <message>. Connection problems
show on the VTube Studio page and in the status bar. Look the message up
below.
Not sure where to start? Check, in this order: VTube Studio is running, its Start API switch (Allow Plugin API access in VTube Studio's docs) is on, CroStream says Connected, and a model is loaded. Setup walks through the first three.
Connection¶
These show on the VTube Studio page and in the status bar. CroStream retries on its own unless the table says you must click Connect.
| Message | What it means | What to do |
|---|---|---|
| CroStream isn't connected to VTube Studio. Open the VTube Studio page and click Connect. (also Click Connect, then allow CroStream in VTube Studio, Not connected) | An action ran with no connection, or you haven't connected yet. | Open Integrations → VTube Studio and click Connect. Turn the integration on under Settings first if it is off. |
VTube Studio isn't running at host:port, or its API is off |
Nothing answered on that address. VTube Studio is closed, the port is wrong, or the PC is unreachable. | Start VTube Studio. Check Port in the VTube Studio page's settings against the one in VTube Studio (8001 by default). If CroStream adds VTube Studio announces port 8002; set Port to 8002, do exactly that. For VTube Studio on another PC, make sure that PC's firewall allows the port. |
| VTube Studio's API is off. Turn on Settings → "Start API". | VTube Studio is running but plugins are switched off. | In VTube Studio open Settings and turn on Start API (Allow Plugin API access in VTube Studio's docs). CroStream connects by itself afterward. |
| Approve CroStream in VTube Studio: a window there asks to allow it / Waiting for you to answer in VTube Studio… | The first connection needs your OK. | Switch to VTube Studio and click Allow in the popup over its window. VTube Studio asks once. |
| You clicked Deny in VTube Studio. Click Connect to ask again. | You declined the approval. Nothing connects until you ask again. | Click Connect, then Allow in VTube Studio. |
| VTube Studio didn't get an answer to the approval window. Click Connect to try again. | The approval popup timed out, or you weren't at the computer. | Click Connect and answer the popup promptly. |
| VTube Studio didn't accept CroStream's approval. Click Connect to approve it again. | VTube Studio rejected the stored approval twice (for example after you reset VTube Studio's plugin list). | Click Connect and Allow again. Forget approval starts clean. |
| VTube Studio's approval for CroStream was revoked. Click Connect to approve it again. / VTube Studio forgot CroStream's approval. | You removed CroStream in VTube Studio's plugin settings, or VTube Studio lost it. | Click Connect and Allow again. |
| Lost the connection to VTube Studio; reconnecting / The connection to VTube Studio dropped. | VTube Studio closed or the network dropped. | Nothing, if VTube Studio is coming back: CroStream reconnects and carries out the changes it was waiting to undo. |
Couldn't connect to VTube Studio at host:port; trying again |
Another failure; the technical reason is on the page. | Same checks as isn't running above; if it keeps failing, copy the reason when you ask for help. |
| VTube Studio didn't answer in time. | VTube Studio froze or is busy (loading a model). | Wait and try again. Close any settings window in VTube Studio. |
Found on your network
The VTube Studio page lists the VTube Studio windows it can see announcing themselves on your network, with Use to switch to one. That is the quickest way to fix a wrong host or port. If the list says it isn't looking, turn on Find VTube Studio on the network under Settings.
Permissions¶
Two things need VTube Studio's separate OK, once each. See Permissions.
| Message | What it means | What to do |
|---|---|---|
| VTube Studio hasn't allowed CroStream to load images. On CroStream's VTube Studio page, click "Ask in VTube Studio" next to Load custom images, then Allow in VTube Studio. | A media, emote or chat emote image needs the load custom images permission. | Do exactly that. Items from VTube Studio's own folder (vts_file) never need it. |
| VTube Studio hasn't allowed CroStream to control NDI. …click "Ask in VTube Studio" next to Control NDI, then Allow in VTube Studio. | The NDI action needs its permission. | Same steps, next to Control NDI. |
| Permission question left unanswered | The permission request is still open in VTube Studio. | Answer it with Allow in VTube Studio, or click Ask in VTube Studio next to the permission to ask again. |
| a permission request is already open in VTube Studio | You asked for a second permission while the first popup is open. | Answer the popup in VTube Studio first. |
VTube Studio: couldn't ask for permission / permission was not granted (Activity feed) |
The popup failed to open, or you declined. | Try again and click Allow. |
VTube Studio granted CroStream permission (Activity feed) |
It worked. | Nothing. |
Actions and limits¶
| Message | What it means | What to do |
|---|---|---|
| No model is loaded in VTube Studio. | The action needs a model (hotkeys, expressions, props, tint, parameters) and none is loaded. | Load a model in VTube Studio. |
No hotkey name on model. / No such hotkey on the loaded model. |
The name or ID isn't on the loaded model, often because you switched models. | Pick the hotkey from the list again. Check spelling and that the right model is loaded. |
No Live2D item with ID id in the scene. / That kind of hotkey can't run in a Live2D item. |
The item was removed, or the hotkey is a kind items don't support. | Check that the item still exists (it may have timed out) and that Live2D item holds its ID. |
No expression file on model. |
The loaded model doesn't have that expression. | Pick it from the list; .exp3.json is added for you. |
| VTube Studio asked to wait a moment. Try again in a few seconds. | A cooldown. A specific hotkey can run once every five frames; a model load or NDI change has a few seconds' cooldown. | CroStream already retried. Space the steps out, or add a delay. |
| VTube Studio's hotkey queue is full. Too many hotkeys at once. | More than 32 hotkeys were waiting in VTube Studio's queue. | Slow down the macro, for example with a queue. |
| VTube Studio has a settings window open. Close it and try again. | VTube Studio refuses model loads and some changes while a settings window is open. | Close the window. |
No model name in VTube Studio. |
The model name or ID isn't in VTube Studio's list. | Pick it from the list. |
| No ArtMesh matched. | A tint matched nothing: the ArtMesh IDs, names, tags or group don't exist on this model. | Pick parts from the VTube Studio page's list, or use Tint the whole model. |
Another plugin is controlling VTube Studio's physics (name). |
Only one plugin can control physics at a time. | Stop that plugin, or wait. |
| This model has no physics. | The model has no physics set up. | Use a different model. |
Another plugin is already setting name. Use mode add, or stop the other plugin. / Another plugin controls this (the parameter). |
Another plugin is holding that tracking parameter. | Set Mode to add, or stop the other plugin. |
No parameter name in VTube Studio. |
The parameter doesn't exist for this model. | Pick it from the list, or create it with Create a custom parameter. |
Another plugin owns a parameter named name. / name is the name of one of VTube Studio's own parameters. Choose another name. / That parameter belongs to another plugin. |
A custom parameter name clash, or trying to delete one you don't own. | Choose another name. Only parameters CroStream created can be deleted. |
No effect named name in VTube Studio. / No effects preset named name. / No such effects preset. |
The effect or preset doesn't exist. | Pick it from the list. |
| VTube Studio doesn't know one of those effect settings, or a value doesn't fit it. | A setting ID in Values is wrong, or a value is out of range or the wrong type. | Check the ID (such as Bloom_Strength) and value. |
| That effect is restricted: allow restricted effects in VTube Studio's effect settings, then turn on Restricted here. | Restricted effects are off in VTube Studio. | Allow them in VTube Studio, then turn on Restricted effect on the step. |
| Width must be a multiple of 16 and height of 8, from 256 to 8192. | NDI size out of range. | Use values like 1920 and 1080. |
The ArtMesh id isn't on this model. Set the "anchor" anchor again. / That ArtMesh isn't on this model. Set the anchor again. |
An anchor refers to a part of a different model or an old version of it. | Re-pick the part for that anchor on the VTube Studio page. |
| No such item in the scene (it may have been removed). | The item ID is stale: the item timed out or someone removed it. | Use the {item_id} from the step that created it, in the same macro. |
| Live2D items can't be animated this way. Use their hotkeys. / This image isn't animated (only brightness and opacity apply). | The wrong kind of item for Control an item's animation. | Use a GIF or a hotkey instead. |
| VTube Studio's scene is full of items. Remove some first. | Too many items. | Use Remove items or the Remove CroStream's items button. |
| No such item file in VTube Studio's Items folder. | The file isn't in VTube Studio's Items folder. | Pick it from the list. |
| Stopped the physics gust: … / Stopped holding VTube Studio parameters: … (Activity feed) | A long hold ended early, for example the connection dropped. | Check the reason that follows; run the action again. |
Couldn't undo: … / Skipped undo: … (Activity feed) |
A timed undo (turn an expression back, move the model back) failed, or was skipped because VTube Studio was disconnected too long. | Fix it by hand, or use Reset everything CroStream changed on the VTube Studio page. |
… isn't a number from a to b / … isn't a duration such as 10s / … must be between a and b |
A step field is outside its allowed range. After the colon it names the field. | Fix the value on the step. The range is in Actions. |
Anchors and props¶
| Message | What it means | What to do |
|---|---|---|
No "nose" anchor for model Akari. On CroStream's VTube Studio page, add it and pick the part. |
The prop's anchor isn't set up for the loaded model. Anchors are saved per model. | Open the VTube Studio page with that model loaded, Add an anchor named nose, and Pick in VTube Studio. See Props & anchors. |
| No anchors yet for this model. Add the first one below, such as "nose". | The loaded model has no anchors. | Add one. |
| Couldn't read the saved VTube Studio anchors, so they start empty: … | The anchors file was damaged. | Re-add your anchors; restore from a backup if you have one. |
| the saved anchors couldn't be read; try again / an anchor with that name exists / anchor names are 1 to 32 characters, without control characters | Messages from the anchors editor. | Retry; pick a different, shorter name. |
| Couldn't take off a prop: … (Activity) | The earlier prop on that anchor could not be removed. | It will go on its own timer. |
| Couldn't put the prop in front of the model: … (Activity) | The prop is on but not sorted in front. | Use Put an item between the model's layers with in_front. |
Images¶
| Message | What it means | What to do |
|---|---|---|
| This image is too large to read (20 MB max). | The file is above CroStream's limit. | Use a smaller file. |
| This image type isn't supported; use PNG, JPG, GIF or WebP. | Any other format. | Convert it. |
| This image couldn't be read. | Damaged file. | Re-export it. |
| This image is too thin to show. | One side is far too small for VTube Studio's 64 px minimum. | Use a less extreme shape. |
| This image is too large for VTube Studio (5 MB max). / This GIF is too large for VTube Studio (5 MB max). | Even after shrinking, VTube Studio would refuse it. GIFs can't be shrunk. | Use a smaller or shorter file. |
| This image has too many pixels to read. | Huge dimensions. | Resize it. |
| VTube Studio refused the image (it must be PNG, JPG or GIF, 64–2048 px, under 5 MB). | VTube Studio rejected the data. | Replace the image. |
| The image was declined in VTube Studio. | You clicked decline on the Ask first window. | Turn Ask in VTube Studio first off, or allow it. |
| VTube Studio already shows 6 image questions. Answer them first. | Too many pending Ask first windows. | Answer them in VTube Studio, or turn off Ask first. |
| There is not enough time left to ask in VTube Studio. | The macro's time budget is too short to wait for your answer. | Use Ask first only on macros that aren't time-critical. |
| The media library isn't available. / Twitch emotes aren't available. | The source isn't connected or isn't ready. | Open the media library or log in to Twitch, then try again. |
| The chat message that ran this macro has no emotes. | Image from is chat_emote and the message had no emotes. |
Only start it from chat events that carry emotes, or use emote. The Test button uses Kappa. |
Unknown emote name: it must have been used in chat since CroStream started, or give its emote ID. |
CroStream only knows emote names it has seen. | Type the emote ID, or use it in chat once. |
The media file couldn't be read. / The image couldn't be read. / The emote name couldn't be loaded. |
The file is missing or the download failed. | Check the file in the media library, or try again. |
Events (triggers)¶
| Message | What it means | What to do |
|---|---|---|
| Needs VTube Studio's beta: expression events aren't available in this version. / This VTube Studio has no expression events (they're in its beta), so expression triggers won't fire. | The expression trigger needs VTube Studio's public beta. | Join VTube Studio's beta, or react to the same expression by its hotkey with the hotkey trigger. Everything else works without it. |
Couldn't subscribe to VTube Studio's event: … |
VTube Studio refused to send that event. | Reconnect; if it repeats, update VTube Studio. |
| A trigger never fires | Not connected; a filter is too narrow; for hotkeys, Run by is still user while a plugin ran it; model-specific filters (a part or hotkey) don't exist on the loaded model. |
Use the trigger's Test button to check the macro, then loosen filters one at a time. Check Activity for the event. |
Still stuck?¶
- Reset everything CroStream changed on the VTube Studio page runs all waiting undos, stops held parameters, removes CroStream's items and clears tints. Use it if the scene is in a mess.
- Forget approval and Connect again fixes most approval trouble.
- See the general Troubleshooting page, and Crash reporting for sending a report.