Background tasks can be tricky to debug since they run when your app is closed. Here's how to effectively debug and troubleshoot them on both platforms.

Hook-Based Debug System

The Workmanager plugin uses a hook-based debug system that allows you to customize how debug information is handled.

Quick Setup

Initialize Workmanager without any debug parameters:

Then set up platform-specific debug handlers as needed.

Android Debug Handlers

Logging Debug Handler (Recommended)

Shows debug information in Android's Log system (visible in adb logcat):

Notification Debug Handler

Shows debug information as notifications (requires notification permissions):

iOS Debug Handlers

Logging Debug Handler (Recommended)

Shows debug information in iOS's unified logging system:

Notification Debug Handler

Shows debug information as notifications:

Custom Debug Handlers

Create your own debug handler for custom logging needs:

For detailed information about task statuses, lifecycle, and notification formats, see the Task Status Tracking guide.

Android Debugging

Job Scheduler Inspection

Use ADB to inspect Android's job scheduler:

Monitor Job Execution

Common Android Issues

Tasks not running:

• Check battery optimization settings
• Verify app is not in "App Standby" mode
• Ensure device isn't in Doze mode
• Check if constraints are too restrictive

Tasks running too often:

• Android enforces minimum 15-minute intervals for periodic tasks
• Use appropriate constraints to limit execution

Debug Commands

iOS Debugging

Console Logging

iOS background tasks have limited execution time. Add detailed logging:

Xcode Debugging

For Background Fetch tasks: Use Debug → Perform Fetch from the Xcode run menu while your app is running.

For BGTaskScheduler tasks (processing/periodic): Use Xcode's console to trigger tasks manually:

Monitor Scheduled Tasks

Check what tasks iOS has scheduled:

This prints output like:

General Debugging Tips

Add Comprehensive Logging

Test Task Logic Separately

Create a way to test your background logic from the UI:

Monitor Task Health

Track when tasks last ran successfully:

Platform-Specific Testing

Android Testing Workflow

1. Enable debug mode and install app
2. Schedule task and verify it appears in job scheduler
3. Put device to sleep and wait for execution
4. Check debug notifications to confirm execution
5. Use ADB commands to force execution if needed

iOS Testing Workflow

1. Test on physical device (simulator doesn't support background tasks)
2. Enable Background App Refresh in iOS Settings
3. Use Xcode debugger to trigger tasks immediately
4. Monitor Xcode console for logging output
5. Check iOS Settings > Battery for background activity

Troubleshooting Checklist

Quick Checks:

• Workmanager initialized in main()
• Task names are unique
• Platform setup completed (iOS setup guide)
• Debug handler configured (see Debug Handlers)

Performance & Reliability:

• Task logic optimized for background execution
• Dependencies initialized in background isolate
• Error handling with try-catch blocks
• iOS 30-second execution limit respected

Remember: Background task execution is controlled by the operating system and is never guaranteed. Always design your app to work gracefully when background tasks don't run as expected.