Error Handling

All SDK errors extend FoundationModelsError. Generation-specific errors extend GenerationError, which itself extends FoundationModelsError. TSFM also adds ServiceCrashedError and ToolCallError.

INFO

The Swift equivalent is LanguageModelSession.GenerationError.

Error Hierarchy

FoundationModelsError

All errors inherit from FoundationModelsError.

GenerationError — errors during generation:

• ExceededContextWindowSizeError
• AssetsUnavailableError
• GuardrailViolationError
• UnsupportedGuideError
• UnsupportedLanguageOrLocaleError
• DecodingFailureError
• RateLimitedError
• ConcurrentRequestsError
• RefusalError
• InvalidGenerationSchemaError
• ServiceCrashedError

ToolCallError — a tool's call() method threw

Catching Errors

import {
  ExceededContextWindowSizeError,
  GuardrailViolationError,
  RateLimitedError,
} from "tsfm-sdk";

try {
  await session.respond("...");
} catch (e) {
  if (e instanceof ExceededContextWindowSizeError) {
    // Start a new session — context window is full
  } else if (e instanceof GuardrailViolationError) {
    // Content policy was triggered
  } else if (e instanceof RateLimitedError) {
    // Too many requests — wait and retry
  }
}

Error Reference

ExceededContextWindowSizeError

The session's accumulated context has exceeded the model's limit. All content (instructions, prompts, responses, tool schemas, tool calls, and tool output) share one context window. Long conversations or large tool outputs will eventually hit this. Dispose the session and start a new one, optionally seeding it with a trimmed transcript. Apple recommends splitting large tasks across multiple sessions.

AssetsUnavailableError

The on-device model files haven't finished downloading. This typically happens right after enabling Apple Intelligence or after a macOS update. Call model.waitUntilAvailable() before creating a session — it will resolve once the assets are ready.

GuardrailViolationError

The model's safety guardrails flagged the prompt or the generated response. With DEFAULT guardrails, this means unsafe content was detected and blocked. With PERMISSIVE_CONTENT_TRANSFORMATIONS, you should see this less often as the model will attempt to transform content instead of rejecting it. Either way, you should attempt to catch this and surface a user-friendly message.

UnsupportedGuideError

A GenerationGuide on one of your schema properties isn't supported by the current model version. This can happen if you use a guide that was introduced in a newer OS version than the user is running. Check your guide types against the guides reference.

UnsupportedLanguageOrLocaleError

The system locale or the language of the prompt isn't supported by the on-device model. Foundation Models supports a subset of languages — this error means you've hit one it can't handle.

DecodingFailureError

The model generated output during structured generation, but it couldn't be decoded into your schema. This can happen with complex or deeply nested schemas. Simplify the schema or add more descriptive property descriptions to guide the model.

RateLimitedError

Too many requests to the on-device model in a short window. This is an OS-level rate limit, not a network API limit. Back off and retry after a short delay.

ConcurrentRequestsError

You called a generation method on a session that's already processing a request. The SDK serializes calls internally via _enqueue(), so you shouldn't normally hit this. If you do, check that you're awaiting calls or use session.isResponding to check state before calling.

RefusalError

The model declined to generate a response. This is distinct from GuardrailViolationError — refusal means the model chose not to answer (e.g., the prompt asks for something outside its capabilities), not that a content filter triggered.

InvalidGenerationSchemaError

Your GenerationSchema is malformed or was rejected by the on-device model. Common causes: unsupported property types, conflicting guides, or schemas that are too complex for the model to constrain. Also thrown when the native layer returns a ModelManagerError Code=1041 rejection.

ServiceCrashedError

The Apple Intelligence background service (generativeexperiencesd) has crashed. This is an OS-level issue, not an SDK bug. The error message includes the restart command:

launchctl kickstart -k gui/$(id -u)/com.apple.generativeexperiencesd

After restarting the service, create a new session and retry.

ToolCallError

Your tool's call() method threw during execution. The SDK wraps the original error with the tool name so you can identify which tool failed and why. Access the original error via err.cause.

Catching All SDK Errors

import { FoundationModelsError } from "tsfm-sdk";

try {
  await session.respond("...");
} catch (e) {
  if (e instanceof FoundationModelsError) {
    console.error("SDK error:", e.message);
  }
}