Skip to content

Troubleshooting

The usual suspects, grouped by symptom. Turn on the NPC's debugToolCalls whenever you're debugging actions — it logs every tool the AI invokes and what it returned.

NPC doesn't respond at all

  • Is a provider set? The NPC needs a Text provider — check providerOverride (a handle) and that the key is registered in the Provider Manager.
  • Is enableTextChat on?
  • Are you within interactionRange?

NPC won't perform an action

  • Is the action in the NPC's manifest (Action Designer ▸ Actions)?
  • Is the AI description clear about when to use it? Vague descriptions get ignored.
  • For a custom action, is the script on the NPC's GameObject or in its Action Scripts list, and does the Script function name match your method?
  • Turn on debugToolCalls — if you see the call but it failed, your handler likely returned NPC.CommandError (read the message).

NPC only does one of several things I asked

"Turn all three lights green" but only one changes? The NPC runs an action loop capped by maxToolRounds (NPC ▸ Advanced, default 4). If it's set to 1, the AI gets a single acting turn — and a model that emits one action at a time can't continue.

  • Raise maxToolRounds (4–8) so it can act, see the result, and act again.
  • Or design the action to take multiple targets at once (e.g. a list, or an "all" value) so one call does the lot — best for weaker models.
  • With debugToolCalls on, the log shows round N/M and how many tool calls each round — if the model only ever emits one call total, prefer the multi‑target design or a stronger provider. See Action Designer ▸ Multi‑step actions.

World event does nothing

  • Does the Event ID match the string in NPC.Notify exactly?
  • Is React immediately on (Events tab)? If off, the NPC only remembers it for later.
  • Do the template's {placeholders} match the JSON keys your script sends? A missing key renders blank.

NPC won't say the player's name

  • Use Player.GetUsername(id) (the validated account name).
  • At OnPlayerLeft the player is gone, so name/position read blank — capture the name at OnPlayerJoined and remember it. See Player API.

No voice / NPC is silent

  • Is enableVoice on and voiceProviderOverride set to a Voice provider handle?
  • Is a player within hearingRange?
  • Try voiceDelivery = Buffered — it's the most reliable; Streamed needs a streaming‑capable endpoint. See Voice.

Storage forgets things after a while

  • Storage is soft memory — it's wiped when the world instance restarts. That's expected. For anything durable, write to your DB via HTTP, keyed by Player.GetUserId. See Storage.

Upload fails

  • No spawn point — set a primarySpawnPoint on the WorldDescriptor.
  • Too large — the SDK reports the size limit; optimize meshes/textures and rebuild.
  • Validation errors — fix what the build step lists before uploading.

My thumbnail keeps getting replaced

  • On re‑upload, tick "Don't override picture" to keep the existing thumbnail. See Worlds.

Script won't compile

  • Check you're inside the sandbox: no file I/O, reflection, arbitrary .NET, or raw sockets — use the platform APIs (HTTP.*, Storage.*, …) instead.
  • Confirm your class extends NexusBehaviour and lifecycle methods use the right form (protected override void Start(), plain void OnTriggerEnter(...)).

Still stuck?

Reproduce it with debugToolCalls on and the console open — the logs usually name the exact failing piece (a missing handler, an unknown event id, a provider error).