Debugging

Learn more about Mintlify

Enter your email to receive updates about new features and product releases.

Console Logging
Backend Logging
Frontend Logging
Network Debugging
Check Backend Endpoints
CORS Issues
Check Network in DevTools
WebRTC Issues
Common WebRTC Errors
Mobile WebRTC Debugging
Function Execution Debugging
Functions Not Loading
Backend vs Frontend Functions
Function Not Executing
Environment Variable Issues
Variables Not Loading (Web)
Variables Not Loading (Mobile)
Generate Module Loaders
Common Error Messages
Debugging Checklist
Getting More Help
Next Steps

This guide helps you debug common issues when working with NAVAI voice-first navigation.

Console Logging

Enable detailed logging to diagnose issues:

Backend Logging

Add logging to your Express server:

server.ts

import express from "express";
import { registerNavaiExpressRoutes } from "@navai/voice-backend";

const app = express();

// Log all requests
app.use((req, res, next) => {
  console.log(`[${new Date().toISOString()}] ${req.method} ${req.path}`);
  next();
});

app.use(express.json());

registerNavaiExpressRoutes(app);

// Error logging middleware
app.use((err, req, res, next) => {
  console.error('Error:', err);
  res.status(500).json({ error: err.message });
});

Frontend Logging

Monitor agent state and events:

import { useWebVoiceAgent } from "@navai/voice-frontend";

const agent = useWebVoiceAgent({
  navigate,
  moduleLoaders: NAVAI_WEB_MODULE_LOADERS,
  defaultRoutes: NAVAI_ROUTE_ITEMS,
  env: import.meta.env
});

// Log state changes
React.useEffect(() => {
  console.log('Agent status:', agent.status);
  console.log('Is connected:', agent.isConnected);
  console.log('Is connecting:', agent.isConnecting);
  if (agent.error) {
    console.error('Agent error:', agent.error);
  }
}, [agent.status, agent.isConnected, agent.isConnecting, agent.error]);

Network Debugging

Check Backend Endpoints

Verify health endpoint

curl http://localhost:3000/health

Expected response:

{"ok": true}

Test client secret endpoint

curl -X POST http://localhost:3000/navai/realtime/client-secret \
  -H "Content-Type: application/json" \
  -d '{}'

Expected response:

{
  "value": "rcs_...",
  "expires_at": 1234567890
}

List available functions

curl http://localhost:3000/navai/functions

Expected response:

{
  "items": [
    {"name": "function_name", "description": "...", "source": "..."}
  ],
  "warnings": []
}

CORS Issues

CORS errors prevent the frontend from communicating with the backend.

Fix CORS configuration:

server.ts

import cors from "cors";

// Configure CORS properly
const corsOrigin = process.env.NAVAI_CORS_ORIGIN?.split(",").map((s) => s.trim()) ?? "*";
app.use(cors({ origin: corsOrigin }));

.env

NAVAI_CORS_ORIGIN=http://localhost:5173,http://localhost:3000

Check Network in DevTools

Open browser DevTools (F12)
Go to Network tab
Filter by “navai”
Look for failed requests
Check request/response details

WebRTC Issues

Common WebRTC Errors

WebRTC native module not found (Mobile)

Cause: Opening app in Expo Go instead of development build.Solution:

# Install development build
npm run android --workspace @navai/playground-mobile -- --device

# Start Metro with dev client
npm run dev --workspace @navai/playground-mobile -- --dev-client

# Open the installed app (NOT Expo Go)

Microphone permission denied

Cause: User denied microphone access or permission not requested.Solution for Web:

Check browser console for permission errors
Ensure HTTPS is used in production
Clear browser permissions and try again

Solution for Mobile:

Verify RECORD_AUDIO permission in app.json
Check device Settings > Apps > Your App > Permissions
Reinstall the app to trigger permission prompt

api_version_mismatch error

Symptom: Realtime WebRTC negotiation failed (400) - “You cannot start a Realtime beta session with a GA client secret”Cause: Mixing beta/GA endpoints during WebRTC negotiation.Solution:

Use GA endpoint: https://api.openai.com/v1/realtime/calls
Remove openai-beta: realtime=v1 header if present
Reinstall app after updating transport configuration

Network thread crash (Android)

Symptom: App crashes with Fatal signal 6 (SIGABRT) in org.webrtc.NetworkMonitorCause: Missing network/audio permissions for WebRTC.Solution in app.json:

{
  "expo": {
    "android": {
      "permissions": [
        "INTERNET",
        "ACCESS_NETWORK_STATE",
        "ACCESS_WIFI_STATE",
        "MODIFY_AUDIO_SETTINGS",
        "RECORD_AUDIO"
      ]
    }
  }
}

Then rebuild and reinstall the app.

Mobile WebRTC Debugging

Check Android logcat

adb logcat | grep -i "webrtc\|navai\|audio"

Verify backend reachability

From mobile device, test endpoints:

# For Android emulator
curl http://10.0.2.2:3000/health

# For physical device (use your LAN IP)
curl http://192.168.1.100:3000/health

Check environment variables

Verify mobile .env configuration:

# Android emulator
NAVAI_API_URL=http://10.0.2.2:3000

# Physical device
NAVAI_API_URL=http://192.168.1.100:3000

Function Execution Debugging

Functions Not Loading

If your functions aren’t available, check the function folder configuration.

Verify NAVAI_FUNCTIONS_FOLDERS

.env

NAVAI_FUNCTIONS_FOLDERS=src/ai/...

Common patterns:

src/ai/... - All files in src/ai recursively
src/ai/functions-modules - Specific folder
src/ai/*.ts,src/utils/*.ts - Multiple patterns

Check function exports

Ensure your function modules export correctly:

src/ai/example.ts

export const name = "example_function";
export const description = "Example function";

export async function run(payload: any) {
  console.log('Function executed:', payload);
  return { success: true };
}

Check warnings

Query the functions endpoint to see warnings:

curl http://localhost:3000/navai/functions

Look at the warnings array for module loading issues.

Backend vs Frontend Functions

Understand where functions execute:

// Backend function (packages/voice-backend/src/functions)
// - Has access to server resources
// - Can access databases, file system, etc.
// - Executed on server via /navai/functions/execute

// Frontend function (packages/voice-frontend/src/functions)
// - Runs in browser/mobile app
// - Has access to navigation, local state, etc.
// - Executed directly in the client

Function Not Executing

Check function name conflicts

Function names must be unique. Reserved names:

navigate_to
execute_app_function

Invalid characters in names will cause functions to only be available via execute_app_function.

Verify payload format

Functions receive payload in specific format:

// For regular functions
{ args: [arg1, arg2, arg3] }

// For class methods
{ 
  constructorArgs: [arg1],
  methodArgs: [arg2, arg3]
}

Check error responses

Look for execution errors:

const result = await fetch('/navai/functions/execute', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    function_name: 'my_function',
    payload: { args: ['test'] }
  })
});

const data = await result.json();
console.log('Execution result:', data);
// Check for: ok: false, error, details

Environment Variable Issues

Variables Not Loading (Web)

In Vite, environment variables must be prefixed with VITE_ to be exposed to the client. However, NAVAI uses NAVAI_ prefix.

Solution: NAVAI handles this internally. Use NAVAI_ prefix:

.env

NAVAI_API_URL=http://localhost:3000
NAVAI_FUNCTIONS_FOLDERS=src/ai/functions-modules
NAVAI_ROUTES_FILE=src/ai/routes.ts

Variables Not Loading (Mobile)

Expo doesn’t support import.meta.env. Variables must be loaded through app.config.js and expo-constants.

Create .env file

apps/playground-mobile/.env

NAVAI_API_URL=http://10.0.2.2:3000
NAVAI_FUNCTIONS_FOLDERS=src/ai/functions-modules

Verify app.config.js exists

app.config.js

module.exports = ({ config }) => ({
  ...config,
  extra: {
    NAVAI_API_URL: process.env.NAVAI_API_URL,
    // other variables...
  }
});

Restart Metro

Changes to .env require Metro restart:

# Stop Metro (Ctrl+C)
# Start again
npm run dev --workspace @navai/playground-mobile

Generate Module Loaders

Forgetting to generate module loaders causes “No generated module loaders were found” error.

Solution:

# For web
npm run generate:ai-modules --workspace @navai/playground-web

# For mobile
npm run generate:ai-modules --workspace @navai/playground-mobile

Common Error Messages

Error	Cause	Solution
`Missing openaiApiKey`	No API key configured	Set `OPENAI_API_KEY` in `.env`
`OpenAI client_secrets failed (401)`	Invalid API key	Verify your OpenAI API key
`Unknown or disallowed function`	Function not in registry	Check `NAVAI_FUNCTIONS_FOLDERS`
`Unknown or disallowed route`	Route not in routes file	Verify `NAVAI_ROUTES_FILE`
`Invalid client-secret response`	Backend not responding	Check backend is running
`Failed to load backend functions`	Network or CORS issue	Verify CORS and network

Debugging Checklist

When encountering issues, check:

Getting More Help

Troubleshooting (Mobile)

See mobile-specific troubleshooting guide

Report Issues

Report bugs and request features

Enable verbose logging in both backend and frontend during development to catch issues early.

Next Steps

Deployment

Learn how to deploy NAVAI to production

Multilingual Support

Deployment

⌘I

Build docs developers (and LLMs) love

Get started for free Talk to us

Get Started

Core Concepts

Backend Integration

Frontend Integration

Mobile Integration

Guides

Console Logging

Backend Logging

Frontend Logging

Network Debugging

Check Backend Endpoints

CORS Issues

Check Network in DevTools

WebRTC Issues

Common WebRTC Errors

Mobile WebRTC Debugging

Function Execution Debugging

Functions Not Loading

Backend vs Frontend Functions

Function Not Executing

Environment Variable Issues

Variables Not Loading (Web)

Variables Not Loading (Mobile)

Generate Module Loaders

Common Error Messages

Debugging Checklist

Getting More Help

Troubleshooting (Mobile)

Report Issues

Next Steps

Deployment

Build docs developers (and LLMs) love

Get Started

Core Concepts

Backend Integration

Frontend Integration

Mobile Integration

Guides

​Console Logging

​Backend Logging

​Frontend Logging

​Network Debugging

​Check Backend Endpoints

​CORS Issues

​Check Network in DevTools

​WebRTC Issues

​Common WebRTC Errors

​Mobile WebRTC Debugging

​Function Execution Debugging

​Functions Not Loading

​Backend vs Frontend Functions

​Function Not Executing

​Environment Variable Issues

​Variables Not Loading (Web)

​Variables Not Loading (Mobile)

​Generate Module Loaders

​Common Error Messages

​Debugging Checklist

​Getting More Help

Troubleshooting (Mobile)

Report Issues

​Next Steps

Deployment

Build docs developers (and LLMs) love

Console Logging

Backend Logging

Frontend Logging

Network Debugging

Check Backend Endpoints

CORS Issues

Check Network in DevTools

WebRTC Issues

Common WebRTC Errors

Mobile WebRTC Debugging

Function Execution Debugging

Functions Not Loading

Backend vs Frontend Functions

Function Not Executing

Environment Variable Issues

Variables Not Loading (Web)

Variables Not Loading (Mobile)

Generate Module Loaders

Common Error Messages

Debugging Checklist

Getting More Help

Next Steps