Skip to content

fix(ios): map iOS 27 typed errors to stable codes - #34

Merged
corasan merged 4 commits into
mainfrom
fm27/typed-errors
Oct 16, 2026
Merged

corasan merged 4 commits into
mainfrom
fm27/typed-errors

Conversation

@corasan

@corasan corasan commented Sep 23, 2026 •

Copy link
Copy Markdown
Collaborator

Relation to #40

#40 landed a smaller fix for the same issue on main. This PR is rebased onto it and replaces FoundationModelsErrorMapping.swift with GenerationFailure.swift, which the rest of the stack builds on. It keeps #40's distinct TRANSCRIPT_MUTATION_WHILE_RESPONDING code, its rule that only a model overflow triggers recovery, and its literal-code and ToolCallError test coverage.

Why

iOS 27 deprecates LanguageModelSession.GenerationError. It throws LanguageModelError, LanguageModelSession.Error, SystemLanguageModel.Error, and GeneratedContent.ParsingError instead. The session mapped only GenerationError, so on iOS 27 these errors got the generic SESSION_RESPONSE_ERROR or SESSION_STREAMING_ERROR code. Context-overflow recovery also did not run.

I reproduced this on main on the iOS 27.0 simulator. A prompt larger than the 4096-token context rejected with SESSION_RESPONSE_ERROR ("The session's transcript exceeded the model's context size."), and wasContextReset stayed false.

Scope

  • package/ios/GenerationFailure.swift adds AppleAIError(generationFailure:during:). It is the one place that turns any thrown error into an AppleAIError. It has one mapping function per error family.
  • The codes are one GenerationFailureCode enum in AppleAIErrors.swift. Each case has one summary line, and one failed builder writes every message. AppleAIError.generationError carries the enum, not a free string, so a typo in a code does not compile. The unused ErrorInfo struct is removed.
  • respond and streamResponse now have one catch each. That catch calls the initializer. Context recovery runs only when AppleAIError.requiresContextRecovery(after:) is true, which means the model itself overflowed (GenerationError.exceededContextWindowSize or LanguageModelError.contextSizeExceeded). An AppleAIError passed through directly or inside a ToolCallError never resets the session.
  • An iOS 27 error gets the same code as its iOS 26 equivalent (CONTEXT_EXCEEDED, GUARDRAIL_VIOLATION, REFUSAL, RATE_LIMITED, SESSION_BUSY, ASSETS_UNAVAILABLE, DECODING_FAILURE, UNSUPPORTED_GUIDE, UNSUPPORTED_LANGUAGE_OR_LOCALE).
  • New codes: UNSUPPORTED_CAPABILITY, UNSUPPORTED_TRANSCRIPT_CONTENT, TIMEOUT, TRANSCRIPT_MUTATION_WHILE_RESPONDING.
  • iOS 27 symbols are inside #if compiler(>=6.4) and #available(iOS 27.0, *).
  • docs/docs/api-reference.md now lists all error codes.
  • The example app now adopts the UIScene lifecycle (enableSceneSupport, Expo SDK 57 patch update). Without this change the app traps at launch on iOS 27. The later PRs in this stack need the example app to run.

errors.ts does not list the codes (code is a string), so the TS layer did not need a change.

Tradeoffs

  • The error code is still the only structured field that goes to JS. rateLimited.resetDate and contextSizeExceeded.tokenCount go into the message text only. To send them as details, the Nitro error bridge must change. I kept that out of this PR.

Blast Radius

The change touches only the error path of respond and streamResponse. Successful responses do not change. On iOS 26, GenerationError gives the same codes and messages as before. On iOS 27, callers that matched on SESSION_RESPONSE_ERROR / SESSION_STREAMING_ERROR for these failures now get the specific codes. The example app dependency update affects only example/.

Verification

  • bun run test (35 pass), bun run typecheck, bun run lint, and bun run format:check pass.
  • bun run test:swift passes. It includes the new GenerationFailureTests. The tests check that each iOS 27 error gets the same code as its deprecated iOS 26 equivalent, that both overflow errors produce .contextExceeded, and that unmapped errors fall back to the correct code for each operation. A mutation that drops the ParsingError mapping makes the tests fail.
  • I compiled the #else branch on the host (I set the guard to an impossible compiler version), and its tests pass. I did not build with Xcode 26, because it is not installed.
  • The example app builds with Xcode 27.1 against the iOS 27.1 simulator SDK.
  • Runtime, iPhone 18 Pro simulator, iOS 27.0, real on-device model (checkFoundationModelsAvailability() gives available):
    • An oversize prompt through respond rejects with CONTEXT_EXCEEDED, and wasContextReset is true. Before this change it was SESSION_RESPONSE_ERROR / false.
    • An oversize prompt through streamResponse rejects with CONTEXT_EXCEEDED, and wasContextReset is true. Before this change it was SESSION_STREAMING_ERROR / false.
    • After recovery, the same session answers the next prompt.
    • I did not trigger a guardrail error at runtime. The model declined the unsafe prompt in plain text and did not throw.

Closes #20

@corasan corasan changed the title fm27/typed errors fix(ios): map iOS 27 typed errors to stable codes Sep 23, 2026
@corasan
corasan added this pull request to stack #36 September 23, 2026 19:32
iOS 27 traps apps that do not adopt the scene lifecycle. Enable
expo-build-properties enableSceneSupport and update Expo to the SDK 57
patch that ships EXExpoAppSceneDelegate.
iOS 27 throws LanguageModelError, LanguageModelSession.Error,
SystemLanguageModel.Error and GeneratedContent.ParsingError instead of
the deprecated GenerationError. These fell through to the generic
SESSION_RESPONSE_ERROR and SESSION_STREAMING_ERROR codes, and context
overflow never ran recovery.

Map every family in one AppleAIError initializer so respond and
streamResponse share one catch. Add UNSUPPORTED_CAPABILITY,
UNSUPPORTED_TRANSCRIPT_CONTENT and TIMEOUT. Guard iOS 27 symbols with

Closes #20
…n model overflow

Restores two behaviors from #40: TRANSCRIPT_MUTATION_WHILE_RESPONDING is its own code instead of SESSION_BUSY, and a passed-through AppleAIError.contextExceeded no longer resets the session. Tests now check every iOS 26 GenerationError against a literal code on every host and cover ToolCallError.
@corasan
corasan merged commit 130c2a4 into main Oct 16, 2026
6 checks passed
@corasan
corasan deleted the fm27/typed-errors branch October 16, 2026 23:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Map iOS 27 typed Foundation Models errors to stable codes

1 participant