Troubleshooting

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

Common Issues

isAvailable() returns false

If isAvailable() consistently returns false, 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) {
    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.

After enabling Apple Intelligence, the system may need to download models. This can take several minutes. isAvailable() will return false until the download completes.

iOS Fallback responses

On iOS versions below 26, the module returns a fallback message. This allows you to develop and test your app on older devices while still building the UI.

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.

Preparation owns the download and resolves only when the model is ready. Later calls return immediately.

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:

Check the GitHub Issues for similar problems and solutions.
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

Found a bug?

We welcome bug reports and contributions! Please open an issue on GitHub with as much detail as possible.