KSCrash 2.6: An iOS and macOS Crash Reporter That Writes Full Apple-Format Reports

What KSCrash solves, and who it is actually for

Apple's own crash reports are hard to get off a user's device and harder to make complete. KSCrash exists to close that gap: it catches crashes inside the process, writes a report in Apple's format with the fields filled in, and leaves it on disk so your code can send it wherever you want. The README calls it "the best open-source crash reporting framework for Apple platforms" and lists support for iOS, macOS, tvOS, watchOS and visionOS. Treat the superlative as marketing; the platform list is the useful part.

The audience is narrower than the tagline suggests. This is for teams that want the report content and the upload path as separate concerns, and for anyone building an SDK that must capture crashes without clashing with the host app's own reporter. The namespacing feature exists precisely for that second case. If what you want is a dashboard, symbolication and alerting with no server work, KSCrash is one layer below that.

How the monitors and the report pipeline fit together

KSCrash is built as a set of monitors behind a single installation call. The README names the categories it catches: Mach exceptions, signals, C++ and Objective-C exceptions, main thread hangs, and OS-level terminations such as OOM, thermal shutdowns, CPU limits and reboots. Each category is a monitor type, and you select which ones are active through the configuration.

Two mechanisms are worth understanding before you enable them. Hang detection runs a Watchdog monitor that flags main thread hangs of 250ms or more and captures full backtraces; real-time observation is exposed through KSCrash+Hang.h. Termination detection works differently, by comparing previous-run state at launch rather than by catching anything at the moment it happens, and the result is read back from KSCrash.shared.previousTerminationReason. That distinction matters when you are reasoning about what a report can and cannot tell you.

User data is stored in an mmap'd key-value store, which the README describes as having zero crash-time overhead. The report model itself is available as a strongly-typed Swift layer in the KSCrashReportModel module, with MetricKit payload integration in KSCrashMonitors and a sampling profiler in KSCrashProfiler. The repository keeps the C, C++ and Objective-C sources under Sources, with Samples and Benchmarks alongside them.

Installing KSCrash with SPM or CocoaPods and catching your first crash

The README gives two install routes. With Swift Package Manager you add the repository in Xcode under File > Add Packages, or declare it in Package.swift pinned to the 2.6 line. The snippet below is the dependency declaration from the README.

dependencies: [
    .package(url: "https://github.com/kstenerud/KSCrash.git", .upToNextMajor(from: "2.6.0"))
]

CocoaPods users add a single pod line instead. The README pins it to the 2.6 series, so a pod install after this change should resolve to 2.6.0 or later within that series.

pod 'KSCrash', '~> 2.6'

Setup is two statements. You import the recording module (named KSCrash instead when you install through CocoaPods), build a configuration object, and hand it to the shared instance.

import KSCrashRecording // KSCrash for CocoaPods

let config = KSCrashConfiguration()
try KSCrash.shared.install(with: config)

After that call the README says KSCrash catches crashes and stores reports on disk. Nothing is uploaded. To send reports to a server you use an installation, and the README points to KSCrashInstallation.h for the details rather than documenting a concrete transport. Expect to write that part yourself.

Where KSCrash stops and your own code has to start

The largest limitation is structural rather than technical: KSCrash captures and stores, and that is the end of its documented responsibility. The README says plainly that to send reports to a server you use an installation, and defers to a header file. There is no documented retry policy, no queue drain behaviour and no server contract in the README. If you need reports to arrive somewhere, that pipeline is your code and your problem.

There is also a version boundary. The 2.6 release deprecates a set of APIs, and the README's table is not cosmetic: the userInfo property is replaced by a per-key API in KSCrash+UserInfo.h, deadlockWatchdogInterval is replaced by KSCrashMonitorTypeWatchdog, KSCrashMonitorTypeMainThreadDeadlock becomes KSCrashMonitorTypeWatchdog, and KSCrashMonitorTypeMemoryTermination becomes KSCrashMonitorTypeTermination. The callback pair crashNotifyCallback and reportWrittenCallback is replaced by isWritingReportCallback and didWriteReportCallback. enableSigTermMonitoring is removed outright because SIGTERM is now always caught, which means code that relied on toggling it needs a different answer, not a renamed one.

Finally, this is the wrong tool if you are not on an Apple platform, and it is overkill if you only want to know that a crash happened. It is built to produce a complete report, not a count.

KSCrash compared with PLCrashReporter and xCrash

PLCrashReporter is the closest comparison and the one people search for alongside KSCrash. Both are in-process reporters that write Apple-format crash reports locally and leave transport to the caller, so the difference is not the basic model. KSCrash's README goes further in the monitors it advertises: hang detection with backtraces, OS-level termination detection via previous-run state comparison, CPU monitoring with sliding-window averages that mirror Apple's enforcement thresholds, zombie detection, and an optional non-fatal report on warning or critical CPU transitions through enableCPUExceptionReporting. Whether that breadth is worth the extra configuration surface depends on how much of it you plan to switch on.

xCrash comes from a different starting point: it is not an Apple-platform framework, so it is not a drop-in substitute for an iOS app. The comparison only makes sense if you are maintaining sibling codebases on more than one platform and want a consistent crash-capture story, in which case you are choosing between two separate integrations rather than two libraries.

The honest summary is that the three overlap on the core job and diverge on what they report beyond the crash itself. KSCrash's differentiator is the monitor set, and its cost is the configuration and migration work that set implies.

Maintenance, licensing and what a 2.6 upgrade costs

The repository is not archived and the last push was on 2026-09-22, one day before this was written, so the project is being worked on now. The branch layout note from August 2026 says master holds the latest stable release, currently 2.6.0, and that develop is where next-release work happens and where new pull requests should target. If you are filing a fix, sending it to master would put it in the wrong place.

The 2.6.0 release is dated 2026-08-08, following a run of betas through late July and early August. That cadence suggests the deprecation table in the README is the near-term migration cost for anyone on 2.5.x, and the project maintains a dedicated migration guide on its wiki for both the 2.5 to 2.6 step and the older 1.x to 2.0 step. Budget for the renames and for the removed SIGTERM toggle rather than assuming a version bump will compile.

KSCrash is MIT licensed, which is permissive and places few conditions on redistribution; the LICENSE file in the repository is the authoritative text. That is a statement about the licence, not legal advice, and if you are embedding KSCrash inside a product you ship, have your own counsel read the file. The README also notes the project is tested with BrowserStack.

Editorial conclusion

Adopt KSCrash if you need locally captured, fully populated Apple-format reports and you are willing to own the upload path, or if you are embedding crash capture inside your own library. Do not adopt it expecting a hosted dashboard with symbolication and alerting out of the box; the README points at KSCrashInstallation.h and leaves the transport to you. Before committing, verify two things: that your current monitor configuration still compiles against the 2.6 deprecation table, and that your build can reach the KSCrashRecording module or the KSCrash pod under whatever namespacing you use.

Frequently asked questions

Official sources

1. Issues
2. kstenerud/KSCrash on GitHub
3. License: MIT
4. README
5. Releases