Troubleshooting

Solutions for common issues when working with expo-ai-kit.

Common Issues

isAvailable() returns false

First confirm the app was built with the llm option: ["expo-ai-kit", { "llm": true }] in app.json followed by a new native build. A build without it reports false here rather than throwing, and sendMessage() then throws LLM_NOT_ENABLED. Otherwise, check the platform-specific sections below for your device.

import { isAvailable } from 'expo-ai-kit';
import { Platform } from 'react-native';

async function debugAvailability() {
  console.log('Platform:', Platform.OS);
  console.log('OS Version:', Platform.Version);

  const available = await isAvailable();
  console.log('AI Available:', available);

  if (!available) {
    console.log('Check: built with ["expo-ai-kit", { "llm": true }]?');
    if (Platform.OS === 'ios') {
      console.log('Check: Running iOS 26.0+?');
      console.log('Check: Apple Intelligence enabled in Settings?');
    } else if (Platform.OS === 'android') {
      console.log('Check: Device supports ML Kit?');
      console.log('See: https://developers.google.com/ml-kit/genai#prompt-device');
    }
  }
}

iOS Troubleshooting

iOS AI not available

Ensure you're running iOS 26.0 or later on a supported device.

iOS Older iOS versions

On iOS versions below 26 there is no built-in text model: isAvailable() returns false and generation throws a typed DEVICE_NOT_SUPPORTED error. Vision (iOS 17+ for background removal), embeddings (iOS 17+), and downloadable models still work there, so you can design the UI around the missing built-in.

To detect this situation:

import { Platform } from 'react-native';
import { isAvailable } from 'expo-ai-kit';

async function checkSupport() {
  const available = await isAvailable();

  if (Platform.OS === 'ios' && !available) {
    // On iOS < 26, generation calls throw a typed DEVICE_NOT_SUPPORTED error
    console.log('Running on older iOS - on-device generation unavailable');
  }

  return available;
}

Android Troubleshooting

Android iOS DEVICE_NOT_SUPPORTED

The built-in Android model throws a typedDEVICE_NOT_SUPPORTED error when ML Kit cannot run on the device. iOS throws the same code below iOS 26 or when Apple Intelligence is disabled, and unsupported platforms (web) throw it for all generation calls. Check the supported devices list.

import {
  isAvailable,
  prepareBuiltInModel,
  sendMessage,
  ModelError,
} from 'expo-ai-kit';

async function safeMessage(text: string) {
  const supported = await isAvailable();

  if (!supported) {
    console.log('Device does not support on-device AI');
    return null;
  }

  try {
    await prepareBuiltInModel();
    const response = await sendMessage([
      { role: 'user', content: text }
    ]);
    return response.text;
  } catch (error) {
    if (error instanceof ModelError) {
      console.error(error.code, error.modelId, error.message);
    }
    throw error;
  }
}

Android iOS MODEL_NOT_DOWNLOADED

On Android, isAvailable() can return true while the supported model still needs its first-use download. AwaitprepareBuiltInModel() before inference. On iOS, the same error is thrown for apple-fm while the OS is still preparing the Apple Intelligence model assets, retry after the OS finishes.

*_NOT_ENABLED (feature flags)

LLM_NOT_ENABLED, SPEECH_NOT_ENABLED, VISION_NOT_ENABLED, and EMBEDDINGS_NOT_ENABLED mean the app was built without the matching config-plugin option. Every capability is opt-in. Add the option to app.json and make a new native build, a JS-only OTA update cannot enable a feature:

{
  "expo": {
    "plugins": [["expo-ai-kit", { "llm": true, "speech": true, "vision": true, "androidEmbeddings": true }]]
  }
}

The availability calls report the same condition without throwing: isAvailable() returns false, and getSpeechRecognitionAvailability() and getVisionAvailability() return { status: 'unavailable', reason: 'not-enabled' }.

Vision

Debugging Tips

• Test incrementally, Start with simple prompts before complex multi-turn conversations.
• Monitor memory, AI models use significant memory. Watch for memory warnings in development.
• Test on real devices, Simulators and emulators may not fully support on-device AI features.
• Check platform logs, Review Xcode console (iOS) or Logcat (Android) for native errors.

// Create a debug wrapper
const DEBUG = __DEV__;

export function aiLog(...args: any[]) {
  if (DEBUG) {
    console.log('[expo-ai-kit]', ...args);
  }
}

// Usage
aiLog('Checking availability...');
const available = await isAvailable();
aiLog('Available:', available);

Getting Help

If you're still having issues:

1. Check the GitHub Issues for similar problems and solutions.
2. When opening a new issue, include:
   • Device model and OS version
   • expo-ai-kit version
   • Expo SDK version
   • Minimal code to reproduce the issue
   • Full error message and stack trace