Table of Contents

Troubleshooting

Last updated:

Most Avatar Engine issues happen at one of four boundaries: the engine process, the bridge URL, saved-versus-applied settings, or speech clip reachability.

Note

Start by separating "Oscova saved the setting" from "the engine applied the setting." Saving only writes configuration. Applying sends a command to the running engine.

Quick diagnosis

Symptom Most likely boundary First check
Status says Offline Engine process or bridge URL Start the engine and click Refresh Engine.
Engine says it is already claimed Connection ownership Close the old client if it is running, then restart the Avatar Engine.
Status says Catalog issue Engine catalog routes Check avatar and emotion list support in the engine.
Apply to Live Avatar is disabled Unsaved draft or offline engine Save settings, then refresh the engine.
Avatar speaks in browser but not engine Output mode or /tts/ reachability Confirm admin output mode and engine access to Oscova URLs.
Message preview does nothing Message endpoints or offline engine Test message/text and message/clear.
Lips do not move Volume or engine lip-sync input Use a low nonzero speech volume.

Connection checks

  1. Start the Avatar Engine binary.
  2. Confirm Bridge URL in Avatar settings, usually http://127.0.0.1:11318.
  3. Click Save Settings if the form has unsaved changes.
  4. Click Apply to Live Avatar.
  5. If apply fails, check host logs and engine logs.

If the engine runs on another machine, confirm the Oscova host can reach that machine and port. Also confirm the engine machine can reach Oscova's /tts/ URLs when avatar speech is used.

If you edit Bridge URL, the settings screen intentionally clears the previous live status and catalogs. Click Refresh Engine again before applying avatar or expression choices.

The first client to connect owns that Avatar Engine run. If the owning Oscova process exits, crashes, or switches to another bridge URL, the old engine remains claimed because its connection ID is intentionally not stored on disk. Restart that Avatar Engine before connecting again.

Save and apply issues

  • If Apply to Live Avatar is disabled, save the form first and confirm the engine is reachable.
  • If saving works but the engine does not change, use the relevant Apply button.
  • If a section-level apply fails, check whether the engine is running and whether that section's values are valid.
  • If Reset to defaults seems temporary, remember that it changes only the draft until you save.
  • If the next spoken reply reconnects unexpectedly, remember that saving settings invalidates the ready cache by design.
  • If a saved avatar or emotion appears as unavailable, refresh against the correct running engine or choose a value from the live list.

Speech issues

  • If speech does not reach the avatar, confirm the output mode includes the avatar and the current user is an admin.
  • If queueing fails, confirm the synthesized clip URL is absolute and points under /tts/.
  • If the engine is remote, confirm it can download the Oscova /tts/ URL.
  • If speech starts but stops early, try Apply to Live Avatar and queue a shorter test phrase.
  • If text appears but lips do not move, avoid setting Speech Volume to exactly 0%.
  • If playback will not stop, disable read-aloud or call the stop action. This sends speech/stop.
  • If browser-and-avatar timing seems late, remember that Oscova queues the avatar clip after browser playback starts.
  • If avatar-only voice mode resumes too soon or too late, check that synthesis responses include accurate clip duration or WAV metadata.
  • If avatar_speak uses a different voice than chat read-aloud, check Avatar Voice on the Avatar settings screen.

API issues

  • Use /avatarbridge/... routes when calling the engine directly.
  • Call POST /avatarbridge/connect first and send its ConnectionId as Authorization: Bearer <ConnectionId> on every other engine route.
  • A 401 Unauthorized response means the connection ID is missing or incorrect. A 409 Conflict from connect means the engine is already claimed.
  • Use api/avatarbridge/... routes only when calling Oscova's authenticated host proxy.
  • Use /avatarbridge/message/font-size on the engine, not the host proxy route api/avatarbridge/message/font/size.
  • Use /avatarbridge/message/display-duration on the engine, not the host proxy route api/avatarbridge/message/display/duration.
  • Expect speech/queue through the host proxy to reject URLs that are not absolute http or https /tts/ URLs.
  • Do not use the removed byte-stream speech route. Use speech/queue or speech/queue-file.

Visual issues

  • If avatar choices are empty, start the engine and click Refresh Avatars.
  • If emotion choices are empty, select or load an avatar, then click Refresh Emotions.
  • If an avatar or emotion does not apply, confirm the selected name exists in the engine list.
  • If the window looks wrong, reapply Window settings together.
  • If message text is off-screen, use Reset to defaults, save, then apply the message box.
  • If message preview does nothing, confirm the engine supports message/text and message/clear.
  • If a setting applies live but returns after restart, you probably used a section-level Apply without Save Settings.

What to collect

Before reporting a bug, collect:

  • The bridge URL.
  • The exact button or API call that failed.
  • Whether Apply to Live Avatar succeeds.
  • Host logs around AvatarBridgeController or AvatarBridgeService.
  • Engine logs for the matching /avatarbridge request.
  • Whether speech synthesis produced a /tts/ URL.
  • Whether the failing host response was an HTTP error or a JSON response with Success = false.
  • Whether the current user is an admin.