Skip to main content

Troubleshooting Backtrace Cocoa on macOS

Use this guide when a macOS application does not initialize Backtrace, does not deliver a captured native crash after relaunch, or produces unsymbolicated reports. Separate capture, local persistence, network receipt, and symbolication when checking the integration.

Capture Startup Diagnostics​

Enable logging before constructing BacktraceClient, and handle initialization errors instead of silently discarding them with try? or error: nil. See Configure Startup Diagnostics.

Record the installed SDK version, application bundle identifier, application build, architecture, macOS version, and relevant sanitized errors. Keep submission tokens and private crash attachments out of public logs and support messages.

Core Data Model Cannot Be Found​

An initialization error containing persistentRepositoryInitError and Couldn't find model url for name: Model indicates a model lookup failure, not an HTTP submission failure.

  • Inspect the Backtrace framework or resource bundle in the built application, not just the source checkout. Verify that the Model.momd resources are present.
  • Preserve the resources supplied with the SDK, including any resource bundle generated by your package manager.
  • Do not delete the retry database to repair missing model resources. Fix the packaging and rebuild the application.
  • Rebuild and sign the final app after any packaging change. Altering files or symlinks inside an already signed bundle can invalidate its signature.

A Native Report Is Not Visible After Relaunch​

  1. Test with a dedicated application build, outside the debugger, and initialize Backtrace on the next launch. Confirm that initialization succeeds and keep the app running long enough for asynchronous delivery.
  2. Determine whether PLCrashReporter captured a pending source in the configured payload directory. A custom basePath changes this location; do not assume all integrations use the default shared cache.
  3. Check startup diagnostics for repository-save or source-purge failures. Backtrace only makes the saved native report eligible after the source purge succeeds.
  4. Check the submission URL, connectivity, server response, and retry policy. An HTTP 429 or 503 response is retryable; with .none, a failed initial attempt does not receive ordinary automatic retries.
  5. Confirm the report in the correct Backtrace project. The disappearance of a source file alone means neither successful network receipt nor symbolication.

For the exact local-rate-limit, HTTP, and capacity behavior, see Cocoa Report Delivery. Do not reset capacity or retry state by removing the database while the app runs.

Preserve Diagnostic Evidence​

Stop the application before collecting a consistent copy of its database, companion SQLite files, attachments, and metadata. Preserve any diagnostic archives and treat these files as sensitive crash data. Share them only through an approved support channel; do not delete or manually reinsert reports while troubleshooting.

Reports Arrive Without Native Symbols​

Upload the dSYMs from the exact application and library build that produced the crash. A dSYM from a different build is not interchangeable, even when the marketing version matches. Check the UUID for each relevant architecture:

dwarfdump --uuid /absolute/path/to/MyApp.app/Contents/MacOS/MyApp
dwarfdump --uuid /absolute/path/to/MyApp.app.dSYM

See Upload Symbols to Your Project. Record backend receipt and successful symbolication as separate validation results.