Skip to content

Documentation / Troubleshooting

Troubleshooting

ModuleNotFoundError: No module named 'vaani'

Activate the intended environment and install either the approved wheel or the source checkout. PYTHONPATH=src alone is insufficient because VAANI requires installed distribution metadata for provenance.

Version is 1.0.0, not 1.0.0rc9

You installed the current source tree/editable metadata, not the approved RC9 wheel. Source metadata reflects promotion preparation; stable GitHub publication is not complete. For candidate verification, install the exact wheel and check its SHA-256.

FrozenInstanceError or “immutable”

Public setup/profile/policy values and runtime assemblies are immutable. Use direct construction or dataclasses.replace(). For a running call, submit CallUpdate.

InvalidCallSetup

Print error.issues, not only str(error). Common causes:

  • profile route ID has no matching adapter ID;
  • model, voice, or language is absent from the adapter declaration;
  • a language binding is incomplete or inconsistent with CascadeMode;
  • tool schema allows additional properties or handler signature is not exactly (context, arguments);
  • transfer/recording policy names an incapable adapter;
  • required update capabilities are undeclared;
  • VAANI distribution metadata is missing or inconsistent.

Preflight occurs before ownership, so no CallResult is expected.

Provider extra is installed but no public factory exists

Some current public modules expose a profile only (notably ElevenLabs, Groq, Silero, turn detector, and noise cancellation). Do not import private _runtime_adapter helpers. Use only a published public factory or provide a consumer adapter that satisfies the public protocol, and track factory coverage as a separate integration task.

LiveKit handoff feels low-level

That is the current boundary. LiveKitTransportAdapter does not accept a raw worker job and automatically wire room events/audio. The consumer must build a worker bridge to LiveKitCallHandoff. The privately published create-vaani-app==0.1.2 companion Starter CLI generates such a bridge as consumer code. Version 0.1.3 is in progress; its credentialed live path is not verified.

Vertex --validate-live says ready but no call occurs

That command only validates environment presence and explicitly reports connected: false. It is not a live provider or telephony smoke. The proven default Vertex path is credential-free and scripted.

Live smoke exits blocked

Missing credentials, audio fixtures, voice IDs, LiveKit/SIP infrastructure, GCS, or PostgreSQL is a deferred prerequisite—not acceptance evidence. Do not turn a blocked record into a passing claim.

Update is stale or unsupported

For a stale revision, re-read active.revision and reconsider the full business decision. Do not blindly replay it. For UnsupportedUpdate, inspect unsupported_fields and declared_alternatives; the previous configuration remains active.

Result has unknown usage or partial cost

The provider did not supply reliable evidence or the price book lacks a matching rate. UNKNOWN is intentional. Fix the adapter/price-book evidence or relax the consumer measurement requirement; never coerce it to zero.

PostgreSQL report is CONFLICT

The idempotency key already exists with different canonical bytes or digest. Do not overwrite it. Investigate the publisher key derivation and result provenance.

Next: FAQ or testing guide.