Skip to main content
This page covers common issues you might encounter while using AnkiDroid Companion and how to resolve them.

​
Common Issues

​
Error Message

API is not available!
This means either AnkiDroid is not installed or API is disabled from the AnkiDroid app
Appears at: MainActivity.kt:61-62

​
Causes

  1. AnkiDroid is not installed on your device
  2. AnkiDroid API is disabled in AnkiDroid settings
  3. AnkiDroid package is not accessible to the companion app

​
How the Check Works

// From AnkiDroidHelper.java:66-68
public static boolean isApiAvailable(Context context) {
    return AddContentApi.getAnkiDroidPackageName(context) != null;
}

​
Solutions

1. Install AnkiDroid2. Enable AnkiDroid API
  • Open AnkiDroid
  • Go to Settings → Advanced → AnkiDroid API
  • Enable Enable AnkiDroid API
3. Verify Package Access The app queries for AnkiDroid using:
<!-- From AndroidManifest.xml:28-30 -->
<queries>
    <package android:name="com.ichi2.anki" />
</queries>
If you’re on Android 11+, this declaration should allow package visibility.
After enabling the AnkiDroid API or installing AnkiDroid, restart AnkiDroid Companion to ensure the API becomes available.

​
Error Message

AnkiDroid Read Write permission is not granted, please make sure that it is given!
Appears at: MainActivity.kt:66 and MainActivity.kt:111

​
What This Means

The app cannot access AnkiDroid’s database without the READ_WRITE_PERMISSION.

​
Permission Check

// From AnkiDroidHelper.java:73-78
public boolean shouldRequestPermission() {
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.M) {
        return false;
    }
    return ContextCompat.checkSelfPermission(mContext, READ_WRITE_PERMISSION) 
           != PackageManager.PERMISSION_GRANTED;
}

​
Solutions

1. Grant Permission When Prompted
  • When you first open the app, tap Allow on the permission dialog
  • The app will request: com.ichi2.anki.permission.READ_WRITE_DATABASE
2. Grant Permission Manually If you previously denied:
  • Open Android Settings → Apps
  • Find AnkiDroid Companion
  • Tap Permissions
  • Find and enable the AnkiDroid permission
  • Restart AnkiDroid Companion
3. Permission Callback Handling
// From MainActivity.kt:97-115
override fun onRequestPermissionsResult(
    requestCode: Int,
    permissions: Array<out String>,
    grantResults: IntArray
) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults)
    
    for ((index, _) in permissions.withIndex()) {
        val permission = permissions[index]
        val grantResult = grantResults[index]
        if (permission == AddContentApi.READ_WRITE_PERMISSION) {
            if (grantResult == PackageManager.PERMISSION_GRANTED) {
                startApp()
            } else {
                explainError("AnkiDroid Read Write permission is not granted, please make sure that it is given!")
            }
        }
    }
}
This permission is required on Android 6.0 (API 23) and above. On older Android versions, the permission is automatically granted.

​
Possible Causes

1. No Cards Are Due
  • Check AnkiDroid directly to see if you have cards scheduled for review
  • The companion app only shows cards that are currently due in AnkiDroid
2. Wrong Deck Selected
  • Open AnkiDroid Companion
  • Use the deck dropdown to select a different deck
  • Tap Refresh to load cards from the new deck
3. Card Query Returns Null
// From MainActivity.kt:153-164
val card = mAnkiDroid.queryCurrentScheduledCard(deckID)
if (card != null) {
    mAnkiDroid.storeState(deckID, card)
    Notifications.create().showNotification(this, card, deckName, false)
} else {
    // No cards to show.
    val emptyCard = CardInfo()
    emptyCard.cardOrd = -1
    emptyCard.noteID = -1
    mAnkiDroid.storeState(deckID, emptyCard)
    Notifications.create().showNotification(this, null, "", false)
}
4. Complex Card Formatting From the README:
Currently this app only supports simple cards with small texts that doesn’t include any HTML. If your case involves complex scenarios, you can try to implement them or create an issue.

​
Solutions

Check Card Availability
  1. Open AnkiDroid directly
  2. Select the same deck
  3. Check if cards appear there
  4. If cards show in AnkiDroid but not the companion, the cards may have complex HTML
Refresh the App
  1. Open AnkiDroid Companion
  2. Select your deck from the dropdown
  3. Tap Refresh
  4. A notification should appear if cards are available
Check Deck Query The app queries cards using:
// From AnkiDroidHelper.java:190-211
Cursor reviewInfoCursor = mContext.getContentResolver().query(
    FlashCardsContract.ReviewInfo.CONTENT_URI, 
    null, 
    deckSelector, 
    deckArguments, 
    null
);
If the query returns no results, it means no cards are currently scheduled for review in that deck according to AnkiDroid’s scheduling algorithm.

​
Possible Causes

1. Notification Permission Denied On Android 13+, notification permission is required:
<!-- From AndroidManifest.xml:5 -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
2. Notifications Disabled in System Settings Even with permission granted, notifications can be disabled per-app.3. Notification Channel Issues The app creates a notification channel:
// From MainActivity.kt:32-43
private fun createNotificationChannel() {
    val name = "AnkiNotificationChannel"
    val descriptionText = "Channel for anki notifications"
    val importance = NotificationManager.IMPORTANCE_DEFAULT
    val channel = NotificationChannel("channel_id", name, importance).apply {
        description = descriptionText
    }
    
    val notificationManager: NotificationManager =
        getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
    notificationManager.createNotificationChannel(channel)
}

​
Solutions

1. Enable Notification Permission
  • Open Android Settings → Apps → AnkiDroid Companion
  • Tap Notifications
  • Enable All AnkiDroid Companion notifications
2. Check Notification Channel
  • In the same settings screen, ensure AnkiNotificationChannel is enabled
  • Set importance to at least Default
3. Verify Do Not Disturb
  • Check if Do Not Disturb mode is blocking notifications
  • Add AnkiDroid Companion to DND exceptions if needed
4. Test Notification
  • Open AnkiDroid Companion
  • Select a deck with available cards
  • Tap Refresh
  • A notification should appear immediately
If you’ve disabled notifications in system settings, the app cannot override this. You must enable them manually in Android Settings.

​
What the Background Worker Does

The periodic worker checks every 8 hours for new cards when you’ve finished a deck:
// From MainActivity.kt:45-56
private fun startPeriodicWorker() {
    Log.i("BackgroundService", "startBackgroundService called from MainActivity")
    val periodicWorkRequest = PeriodicWorkRequest.Builder(
        PeriodicWorker::class.java,
        8, TimeUnit.HOURS
    ).build()
    WorkManager.getInstance(this).enqueueUniquePeriodicWork(
        "WORKER_ANKI",
        ExistingPeriodicWorkPolicy.REPLACE,
        periodicWorkRequest
    )
}

​
Worker Logic

// From PeriodicWorker.kt:23-54
private fun checkNotifications() {
    var mAnkiDroid = AnkiDroidHelper(applicationContext)
    val localState = mAnkiDroid.storedState
    
    if (localState == null) {
        Log.i("BackgroundService", "Periodic worker - Local state is null")
        return
    }
    
    // This is not an empty card, don't do anything.
    if (localState.cardOrd != -1 || localState.noteID != (-1).toLong()) {
        return
    }
    
    // No card found on local state found, try to get the next scheduled card.
    val nextCard = mAnkiDroid.queryCurrentScheduledCard(localState.deckId)
    if (nextCard != null) {
        mAnkiDroid.storeState(localState.deckId, nextCard)
        Notifications.create().showNotification(applicationContext, 
                                                nextCard, 
                                                mAnkiDroid.currentDeckName, 
                                                false)
    }
}

​
Symptoms

  • Deck finished, but no new notification after 8+ hours
  • Cards are due in AnkiDroid, but companion doesn’t notify

​
Causes

  1. Battery optimization killing the background worker
  2. Android system restricting background work
  3. Worker never started (requires at least one manual refresh)

​
Solutions

1. Disable Battery Optimization
  • Open Settings → Apps → AnkiDroid Companion
  • Tap Battery or Battery optimization
  • Select Don’t optimize or Unrestricted
2. Ensure Worker Was Started The worker only starts after you tap Refresh at least once:
// From MainActivity.kt:167
startPeriodicWorker()
3. Check WorkManager Status You can verify if the worker is scheduled using adb:
adb shell dumpsys jobscheduler | grep "com.ankidroid.companion"
4. Manual Refresh If the worker isn’t running:
  • Open AnkiDroid Companion
  • Tap Refresh to restart the worker
The 8-hour interval is currently hardcoded. As noted in the README, future versions may allow customization of this interval.

​
Getting More Help

If you encounter issues not covered here:
  1. Check the logs - Use Android Logcat to see detailed error messages
  2. Report an issue - Open an issue on the GitHub repository
  3. Check existing issues - Your problem may already be reported with a solution

​
Useful Log Tags

When reporting issues, include logs with these tags:
  • BackgroundService - Worker and AnkiDroid helper logs
  • Notifications - Notification creation and button handling

​
Known Limitations

From the README (README.md:36-44):
Minimalistic Card SupportCurrently this app only supports simple cards with small texts that doesn’t include any HTML. If your cards have complex formatting, they may not display correctly.
Skipping CardsThere’s currently no way to skip a card without answering it. You must select one of the four ease ratings.
Study IntervalThe 8-hour check interval for new cards is hardcoded. This may become configurable in future versions.

Build docs developers (and LLMs) love

Get started for freeTalk to us