Almost every failure in this space is silent. The build succeeds, the code is
generated, the app runs — and Siri has never heard of your action. That is not a
bug in your project; it is what App Intents and AppFunctions do when something
is not where the system expects it, and it is why doctor exists.
Start here, on either platform:
dart run os_intents_cli:os_intents build # everything, in orderThen read the artefact rather than the source:
flutter build ios --simulator --debug
dart run os_intents_cli:os_intents doctordoctor reads the file the OS itself indexes. If your intent is not in its
output, no amount of restarting the phone will help, and the rest of this page
is about why it might not be.
The generated Swift is not in the Runner target. It compiles into nothing, and nothing reports it:
dart run os_intents_cli:os_intents install --checkIf that lists files, run install without --check. doctor on a bundle built
afterwards should then list them.
You did not rebuild. App Intents metadata is extracted by Xcode at compile
time, into Metadata.appintents inside the bundle. Nothing declared at runtime
from Dart is ever visible to the system, and a hot reload changes nothing. After
any change to an annotation: rebuild, and reinstall the app.
iOS has not re-indexed yet. Deleting the app and installing it again is the
blunt fix. On a simulator, xcrun simctl reinstalls are usually enough.
Another AppShortcutsProvider won. iOS selects exactly one per app and
drops the rest without an error or a warning. sync refuses to write ours when
it finds one you wrote yourself, and doctor names the provider the system
actually selected:
Spoken phrases (3 via Runner.OsIntentsShortcuts)
If that says something other than OsIntentsShortcuts, your phrases are in the
losing provider. Move them into @AppIntent(phrases: …) or delete the other
provider.
root.ssu.yaml is missing. doctor reports it on the last line of the
phrases section. Without it Siri has no phrase model, and only the tap paths
work.
The phrase does not name the app. Every phrase has to contain $app, which
expands to \(.applicationName). The generator refuses a phrase without it, so
this fails at build time rather than at App Review.
On Android that is the documented answer: there is nothing to donate to.
On iOS it means one of the links broke, and the check that separates them is
doctor — a donation needs the same generated code an invocation does. Most
often the app was built before OsIntentsDonations.swift existed, or that file
is not in the Runner target:
dart run os_intents_cli:os_intents buildAn id nothing declares also returns false, deliberately: a typo in a donation should not throw in a code path that only exists to help the user later.
Donation is a hint to a ranking model, not an instruction. iOS decides what to
surface from days of real use, so a handful of donations on a simulator will
not produce a suggestion, and nothing in this package can make one appear.
donate returning true means the system accepted the intent — that is the
whole of what is observable.
Execution.foreground opens the app by design. Execution.background does not
— but only on iOS, and only through App Intents. On Android's app-shortcuts
layer every shortcut starts an Activity; see below.
OsIntents.install() has not been called yet. It must run before
runApp:
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
await OsIntents.install($osIntentsRegistry);
runApp(const MyApp());
}An intent can be what launched the app, and the native side buffers that invocation only until this future resolves. Registering after the first frame means the launch that started you is already gone.
The generated background entrypoint carries @pragma('vm:entry-point') because
nothing in Dart references it, and release builds tree-shake it away otherwise —
the engine then fails to start with nothing but a bare false. If you have
edited a generated file by hand, regenerate it.
AppIntent is iOS 16+, but AppIntentsPackage is iOS 17+. os_intents targets
16 deliberately and does not use the latter. If you added an
AppIntentsPackage of your own, that is where the deployment-target error
comes from.
Android is two layers and they fail differently. App shortcuts and Assistant
capabilities are generated by default. AppFunctions — the headless one —
is opt-in behind sync --android. Details in android.md.
The manifest does not point at the generated file.
dart run os_intents_cli:os_intents install --checkAndroid reads res/xml/os_intents_shortcuts.xml only when the launcher activity
carries the matching <meta-data>. install writes it; without it the file is
present, correct and never opened.
It has a required parameter. A tap carries no values and there is nobody to
ask, so a shortcut for it would appear and then fail on use. sync says which
intents this skipped and why:
note: "addTask" gets no launcher shortcut — a tap cannot supply title.
An Assistant capability is exempt: the system fills the built-in intent's parameters before launching anything.
The string resource did not make it into the build. ShortcutManager resolves
labels through the resource table, so this is a packaging problem, and only the
device can report it:
dart run os_intents_cli:os_intents doctor --deviceOn the app-shortcuts layer it always will. A shortcuts.xml <intent> starts
an Activity; there is no way to answer one without a UI, so the plugin routes
the launch into the UI isolate. Headless execution is what the AppFunctions
layer exists for, and it is behind sync --android.
Foreground intents are deliberately absent. An AppFunctionService has no
Activity to bring forward, so offering one would produce an action that always
fails. doctor --android shows which functions reached the APK.
Nothing has been observed end to end here. The bridge is proven, but the
path from a real assistant through AppFunctionService has never run, because
Gemini's integration is in a private EAP. See verified.md.
That layer forces a version chain, and os_intents will not change your build for you:
compileSdk = 37andcompileSdkMinor— Android 17 has minor API levels, so the platform isandroid-37.1andcompileSdkalone does not resolve.- AGP 9.1.1+, Gradle 9.3.1+, and the KSP plugin.
- The
androidx.appfunctionsdependency and its compiler. OsIntentsSetup.configure()fromApplication.onCreate.
For that last one: Flutter's manifest template already carries
android:name="${applicationName}". Install a custom Application by
replacing that placeholder, not by adding a second android:name — the
merger fails on the duplicate with nothing more useful than a parse error.
The generated Kotlin lists every property under <required>, but
androidx.appfunctions treats a nullable property as optional however it is
listed. doctor reports what the runtime will enforce, not what the file says.
build_runner has not run, or no function carries @AppIntent. os_intents build runs it for you.
Messages like "Parameter … is an enum but has no enumTypeName" mean the
manifest is internally inconsistent — regenerate it. This is checked rather than
assumed because an unfilled type name used to be interpolated into generated
Dart, Swift and Kotlin as the literal word null.
The generated files no longer match the manifest. Run os_intents build and
commit the result. Two guards, and they catch different things:
sync --check |
the generated files match the manifest |
install --check |
the native projects reference those files |
An intent id is the contract. It is what a saved shortcut or an automation
points at, and by default it is your function's name — so renaming the function
orphans everything already built on it. Pin it with
@AppIntent(identifier: 'addTask'), and assert on the list in a test:
test('no handler was renamed', () {
expect(IntentHarness($osIntentsRegistry).registeredIds,
['addTask', 'completeTask', 'dueToday']);
});The wire format carries String, int, double, bool, DateTime, a class
annotated @AppEntity, and an enum annotated @AppEnum. returns: is
narrower still — String, int, double, bool, DateTime — because Swift
fixes perform()'s return type at compile time. Both are refused by the
generator rather than compiled into native code that will not build.
verified.md lists what has actually been observed on a device,
what only compiles, and what has never been seen at all — worth checking before
assuming a fault is yours. If it is not there,
open an issue with the output of
os_intents doctor.