Common Issues

Issue: Trigger Popup Appears When Should Be Suppressed

Symptom User dismissed help offer but it reappears immediately or on same screen.

Cause

• Config mismatch or stale SDK config snapshot
• passiveTracker.onInteraction() not called on dismissal

Fix

1. Verify backend flag trigger.suppress_high_time_spent is enabled
2. Check /v1/sdk/config returns expected value
3. Validate AI.getConfig().isFeatureEnabled("suppress_high_time_spent_trigger")
4. Ensure SDK refreshed config (wait interval or restart app)

Prevention

• SDK calls passiveTracker.onInteraction() on dismissal automatically
• Config refresh interval respected

Issue: Agent Responds with Previous Screen Context

Symptom User navigated to new screen but voice agent still references old screen.

Cause Screen transition event not emitted or wrong screen ID mapping.

Fix

1. Add AI.setKycStep(newScreenId) to onResume() of every screen
2. Verify screen ID matches registered schema (if using schemas)
3. Check /api/activity for latest session.screen value

Code Fix

class NewScreenActivity : AppCompatActivity() {
  override fun onResume() {
    super.onResume()
    AI.setKycStep("correct_screen_id")
  }
}

Issue: Activity Payload Duplicated

Symptom Same datum appears in multiple locations in event payload.

Cause SDK or client sending duplicate field placement.

Fix

1. Use one canonical field location per datum
2. Remove redundant copies from properties
3. Check HttpBackendClient for duplicate field injection

Prevention

• SDK updated to strip duplicates in routes/events.py
• Keep top-level fields canonical

Issue: No Trigger Activity

Symptom Events reach backend but no trigger evaluations logged.

Cause

• autoTriggerEnabled = false
• Passive evaluation disabled
• Backend trigger flags off

Fix

1. Check RuntimePolicy.triggerSettings.autoTriggerEnabled
2. Verify passiveEvalEnabled and interval
3. Check backend flags: trigger.v2_scoring, trigger.policy_engine
4. Verify events in /api/activity

Issue: missing_screen_context on Session Start

Symptom Voice session starts but backend logs missing context error.

Cause No screen context available for session.

Fix

1. Call AI.setKycStep(screenId) before AI.startAssistant()
2. Ensure prior events include screen or screen_id
3. Check session has events with screen context

Issue: Voice Does Not Connect

Symptom AI.startAssistant() returns connection error.

Cause

• RECORD_AUDIO permission denied
• LiveKit credentials missing
• Backend dispatch failed

Fix

1. Verify RECORD_AUDIO in manifest and runtime permission
2. Check backend .env has LiveKit URL, key, secret
3. Verify integration.livekit_dispatch flag enabled
4. Inspect /api/activity for session_start payload

Permission Check

if (ContextCompat.checkSelfPermission(this, Manifest.permission.RECORD_AUDIO) 
    != PackageManager.PERMISSION_GRANTED) {
  // Request permission
}

Issue: SDK Not Initialized Error

Symptom SDK method calls fail with not initialized error.

Cause

• AI.init() not called
• Called after process death
• Wrong initialization order

Fix

1. Ensure AI.init() in Application.onCreate()
2. Check initialization before any SDK calls
3. Verify no process death/recovery issues

Issue: Backend 401 Unauthorized

Symptom SDK HTTP calls return 401.

Cause

• Wrong apiKey
• Backend KYCIS_API_KEY not set
• Header mismatch

Fix

1. Verify AI.init(apiKey = "correct-key")
2. Check backend KYCIS_API_KEY env var
3. Confirm X-API-Key header matches

Issue: Events Not in Activity Stream

Symptom SDK calls appear to succeed but no events in /api/activity.

Cause

• Wrong backend URL
• Network failure
• Session store cleared

Fix

1. Verify backendBaseUrl reachable from device
2. Check network logs for HTTP 200
3. Remember: backend restart clears in-memory store