Skip to main content

Common Errors & Solutions

Cannot find NCKit types after SPM​

Symptom: Cannot find 'NCKitModelLocator' in scope (or NCKitProcessor, etc.) even though import NCKit is present.

Cause: Xcode resolved an old package checkout. Use tag 1.2.1 and reset caches.

Fix:

  1. File → Add Package Dependencies → set NCKit to Exact Version 1.2.1

  2. File → Packages → Reset Package Caches

  3. File → Packages → Resolve Package Versions

  4. Product → Clean Build Folder (⇧⌘K)

  5. Confirm the checkout exposes NCKitProcessor:

    Shell
    grep NCKitProcessor ~/Library/Developer/Xcode/DerivedData/*/SourcePackages/checkouts/NCKit/NCKit.xcframework/ios-arm64/NCKit.framework/Modules/NCKit.swiftmodule/arm64-apple-ios.swiftinterface

NCKitError.missingModel​

Symptom: throw NCKitError.missingModel("NCKit_model.tar.gz")

Checklist:

  1. Framework embedding → Embed & Sign
  2. SPM cache — Reset Package Caches
  3. CocoaPods — pod deintegrate && pod install
  4. Clean derived data
  5. Intel Mac simulator — upgrade to 1.2.1 or see Simulator guide

NCKitError.libraryInit​

Cause: df_create() returned nil. On simulator, often an older NCKit without ios-arm64_x86_64-simulator on Intel x86_64.

Fix: Upgrade to 1.2.1+, or use Rosetta simulator / physical device.

NCKitError.unsupportedFormat​

Swift
let asset = AVAsset(url: inputURL)
let tracks = try await asset.loadTracks(withMediaType: .audio)
print("Audio tracks: \(tracks.count)")

NCKitError.cannotCreateOutput​

Swift
let output = FileManager.default.temporaryDirectory
    .appendingPathComponent(UUID().uuidString + ".wav")

Build Error: Missing required module 'CDeepFilter'​

Clean derived data; use prebuilt XCFramework, not source files.

Build Error: Simulator / device slice mismatch​

Confirm full NCKit.xcframework is embedded, not a single slice.

NCKitStreamProcessor missing reset()​

Symptom: reset() not available on NCKitStreamProcessor.

Fix: Upgrade to 1.2.1 (or 1.1.1+), reset package caches, clean build. reset() requires NCKit 1.1.1+.

Mic tap returns 0 Hz​

Ensure the AVAudioEngine graph is connected, microphone permission is granted, and the audio session is active before installing the tap.

Denoise blocks UI​

Run NCKitFileProcessor.processFile inside Task.detached (see How to Use).

Package download fails​

Add your GitHub account under Xcode → Settings → Accounts for private repo access.

Audio Sounds Robotic / Over-Processed​

Swift
let proc = try NCKitProcessor(modelURL: url, attenLimDb: 40)
proc.setAttenLim(40)
proc.setPostFilterBeta(0)