Fix common setup issues.

import Primordial Fails

Confirm that the app target links the Primordial product. Do not link the package only to a test target if app code imports it.

The Project Asks For Extra Packages

The app should not add separate engine or runtime packages for Primordial features. Keep only the Primordial package product.

load() Throws modelNotDownloaded

Confirm activation first, then download and load the model.

try await Primordial.activate(
    .evaluationKey("pk_eval_...")
)

try await llm.download()
try await llm.load()

try await llm.downloadAndLoad()

Voice models follow the same download/load lifecycle.

Download Throws insufficientStorage

Ask the user to free space, remove older downloaded models, or choose a smaller model when available.

do {
    try await llm.download()
} catch PrimordialLLMError.insufficientStorage(let requirement) {
    print(requirement.requiredAvailableBytes)
    print(requirement.availableBytes)
}

Download Was Cancelled

Start download() again. Primordial reuses valid cached state and resumes supported partial transfers.

Voice Permission Fails

Confirm both usage descriptions are present and request authorization before recording.

• NSMicrophoneUsageDescription
• NSSpeechRecognitionUsageDescription

guard await recorder.requestAuthorization() else {
    return
}

Voice APIs Produce Main Actor Errors

@MainActor
func startVoiceFlow() async throws {
    let recorder = PrimordialClient().voiceRecorder()
    try await recorder.startRecording()
}

Released Mobile Builds Fail Integration

This alpha intentionally blocks unsupported distribution contexts. Released mobile builds will require a signed production license generated from the developer console. However, licenses are not available right now.

try Primordial.activate(
    .license(.bundled("Primordial.license"))
)