flutter_local_notifications throws ArgumentError: iOS settings must be set
ArgumentError (Invalid argument(s): iOS settings must be set when targeting iOS platform.)Short answer
The plugin's initialize call checks that InitializationSettings holds settings for the platform the app is running on. If the iOS field is null on an iPhone, it throws this ArgumentError. Pass DarwinInitializationSettings as iOS, and as macOS if you run there; the Android and Linux fields follow the same rule.
Fix it fast
1Find out which cause you have
Find where the plugin is initialised and read which fields of InitializationSettings are filled in.
grep -rn "InitializationSettings(" lib/2Match what you see, then jump to its fix
- 1
The message names iOS and appears only when the app runs on an iPhone or iPad simulator; Android works.The iOS field of InitializationSettings is missingFix - 2
The message says macOS settings or Android settings instead of iOS.The same app also runs on macOS (or Android) and that field is emptyFix - 3
Your code still builds the settings with the old IOSInitializationSettings class, or calls initialize with a positional argument.initialize() is called with a settings object built for the old APIFix
- 1
What does the error look like?
ArgumentError (Invalid argument(s): iOS settings must be set when targeting iOS platform.)Android settings must be set when targeting Android platform.macOS settings must be set when targeting macOS platform.
Cause 1 of 3
The iOS field of InitializationSettings is missing
1Check
Look at the InitializationSettings constructor call. If it only passes android:, the iOS value is null.
grep -rn -A4 "InitializationSettings(" lib/2Fix
Create DarwinInitializationSettings and pass it as iOS. The plugin's README shows this form, and all fields are nullable so you must fill each platform you run on.
const android = AndroidInitializationSettings('app_icon');
const darwin = DarwinInitializationSettings();
const settings = InitializationSettings(android: android, iOS: darwin);
await flutterLocalNotificationsPlugin.initialize(settings: settings);3Verify
Run on an iOS simulator and confirm initialize() completes.
flutter run -d iosConfirmed by pub.dev
Cause 2 of 3
The same app also runs on macOS (or Android) and that field is empty
1Check
Each target platform needs its own field. The same Darwin settings object can be passed to both iOS and macOS.
flutter devices2Fix
Set every platform you ship to. The README passes one DarwinInitializationSettings object to both iOS and macOS.
final settings = InitializationSettings(
android: AndroidInitializationSettings('app_icon'),
iOS: darwin,
macOS: darwin,
);3Verify
Run on each platform you ship and confirm there is no ArgumentError.
flutter run -d macosConfirmed by pub.dev
Cause 3 of 3
initialize() is called with a settings object built for the old API
1Check
Look for IOSInitializationSettings in your code. The README says IOSInitializationSettings extends DarwinInitializationSettings and the current call passes settings by name.
grep -rn "IOSInitializationSettings" lib/2Fix
Switch to DarwinInitializationSettings and the named settings: argument shown in the current README.
await flutterLocalNotificationsPlugin.initialize(
settings: initializationSettings,
onDidReceiveNotificationResponse: onDidReceiveNotificationResponse,
);3Verify
Run flutter analyze and then launch the app.
flutter analyzeConfirmed by pub.dev
How do I stop it coming back?
- Build one InitializationSettings object that lists every platform you ship to.
- Read the package changelog before upgrading flutter_local_notifications; initialisation signatures changed between major versions.
- Run the app once on every target platform after changing initialisation code.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
Related fixes
Mobile apps
Flutter Image.network shows nothing or throws when the image fails
EXCEPTION: resolving an image codec
Image.network throws an exception that goes to FlutterError.onError when a download or decode fails, so a 404 leaves a red screen or an empty box.
3 causes, each with a fixMobile apps
image_picker closes the app or returns nothing after choosing a photo
With launchMode singleInstance the picker always returns RESULT_CANCELED
On Android the system can kill MainActivity while the picker is open, so the app restarts and the result never arrives.
3 causes, each with a fixMobile apps
CLIENT_ID and REVERSED_CLIENT_ID are not in GoogleService-Info.plist
ANDROID_CLIENT_ID is missing from GoogleService-Info.plist
Firebase's Google sign-in steps enable the Google provider first and only then have you download a new GoogleService-Info.plist.
2 causes, each with a fixMobile apps
Scheduled flutter_local_notifications never appear when the app is closed
zonedSchedule does nothing, with no error shown
Local notifications are scheduled with the system, so they should fire while the app is closed.
5 causes, each with a fixMobile apps
Flutter cannot open a file: OS Error No such file or directory
FileSystemException: Cannot open file, path = '...' (OS Error: No such file or directory, errno = 2)
Errno 2 means the exact path you gave does not exist on the device.
3 causes, each with a fixMobile apps
flutter_tts does not speak, or stops early, on Android or iOS
Text to speech works on one phone but not on another
Check platform setup first.
5 causes, each with a fix