xcsym Reference (iOS/macOS Crash Symbolication)
Reference for xcsym, the crash symbolication tool bundled with Axiom. It reads .ips (v1 and v2), MetricKit (MXCrashDiagnostic), Apple's legacy .crash text, and Xcode Organizer .xccrashpoint bundles; finds the matching dSYMs; symbolicates with atos; tags each crash with a pattern_tag; and reports UUID and architecture mismatches for every image. Apple's own tools (atos, symbolicatecrash) produce text meant for a person reading Xcode; xcsym adds dSYM discovery, pattern categorization, and compact JSON, so your assistant can triage a crash in one call.
When to Use This Reference
Use this reference when:
- Looking up the flags for the
crash,verify,resolve,find-dsym,list-dsyms,triage, andanonymizesubcommands - Checking the JSON that
crashemits (tool,version,format,input,crash,images,images_summary,warnings,size_warning) - Interpreting an exit code (
0success,1usage,2input or main dSYM missing,3UUID mismatch,4architecture mismatch,5tool error,6timeout,7partial match,8output error) - Mapping a
pattern_tagto its rule ID, confidence, and signal - Understanding the dSYM discovery order (
--dsym→ cache → Spotlight → Archives → DerivedData → Frameworks → Downloads → Toolchain →--dsym-pathsorXCSYM_DSYM_PATHS) - Handling
.xccrashpointbundles (--filter,--prefer-locally-symbolicated,empty_bundleversusunsupported_format) - Reading the JSON xcsym returns for a hang report (
bug_type=298) or an unsupported format - Choosing
--format=summary,standard, orfull, and reading the size warnings for each tier - Classifying a corpus of grouped crashes and hangs from Sentry or App Store Connect with
triage - Scrubbing a crash for use as a test fixture (what
anonymizescrubs and what it keeps; it keeps dSYM UUIDs so the fixture still symbolicates)
Example Prompts
Questions you can ask your assistant that will draw from this reference:
- "What does
xcsym crashreturn?" - "What pattern tags can xcsym emit?"
- "Why did xcsym exit with code 3?"
- "How does xcsym find dSYMs?"
- "What does anonymize preserve so the fixture still symbolicates?"
- "How do I handle an
.xccrashpointbundle with multiple builds?" - "What's the difference between the
crashandverifyexit codes?" - "Why does xcsym take minutes to symbolicate on my machine?"
What's Covered
- Invocation – In Claude Code,
xcsymis on yourPATHbecause Axiom's session hook adds the plugin'stools/folder; if the bare name isn't found,<plugin-root>/tools/xcsymworks, where<plugin-root>is the installed plugin's folder. Codex runs<plugin-root>/tools/xcsym(there, the folder containing.codex-plugin/plugin.json) unlesscommand -v xcsymfinds it onPATH. In Pi,xcsymisn't on yourPATHuntil you add it (Pi setup). MCP clients call the sevenaxiom_xcsym_*tools (crash,verify,find_dsym,list_dsyms,resolve,triage,anonymize), and a table maps each subcommand and flag to the tool's inputs - MCP limits – MCP tools take file paths, not stdin, so pasted crash text must be saved to a file first. Pass absolute paths, and pass the folders that hold your project's dSYMs as
dsymPaths. The server stops any call at 120 seconds; after a timeout, retry withnoDefaultsplusdsymPaths. Reports are always JSON - Output format – Compact, single-line JSON by default, so it costs your assistant few tokens. Every report subcommand (
crash,verify,resolve,find-dsym,list-dsyms) takes--humanfor a terse prose version, and… | jq .gives indented JSON.anonymizeis the exception: it reproduces the.ipswire format rather than a report, so it has no--human crashsubcommand – The full pipeline (parse → discover dSYMs → symbolicate → categorize → emit JSON), with--format,--human,--from-metrickit,--dsym,--dsym-paths,--no-symbolicate,--no-cache,--no-spotlight,--no-defaults,--output, stdin input, and the.xccrashpointflags. Flags may come before or after the file pathverifysubcommand – Per-image UUID and architecture match diagnostics, with exit codes that differ fromcrashresolvesubcommand – Resolves individual addresses withatosagainst an explicit dSYMfind-dsymsubcommand – Looks up a dSYM by UUID across the discovery chainlist-dsymssubcommand – Inventories dSYMs by source (archives,deriveddata,downloads,toolchain,frameworks,env,all)triagesubcommand – Classifies a JSONL corpus of grouped issues from Sentry or App Store Connect, crashes and hangs alike, into pattern tags, clusters, and noise flags. It runs without symbolication or network access and exits0even when it skips reportsanonymizesubcommand – What it scrubs (bundle IDs, process, app, framework, and binary names, user paths, IP addresses, device names, account IDs, foreign UUIDs in freeform strings, identifying.crashheader fields) and what it keeps (dSYM UUIDs, thread names, library identifiers, the structural fields symbolication depends on)- Output schema – The top-level JSON shape, with
pattern_tag,pattern_confidence,pattern_rule_id,pattern_reason,crashed_thread, andimagessplit into matched, mismatched, and missing - Format tiers –
summary(~2 KB, warns past 4 KB),standard(~12 KB, warns past 50 KB),full(warns past 100 KB) - Exit codes – Codes shared by every subcommand (0, 1, 5, 6, 8) plus symbolication codes (2, 3, 4, 7) that differ by subcommand, including what code 7 means for
crashversusverify, and the hang and resource-warning reportscrashturns away with exit 1 - Pattern tag catalog – The 20 tags
crashcan emit (19 rules plusunclassified) (swift_forced_unwrap,swift_concurrency_violation,swift_fatal_error,zombie_or_heap_corruption,stack_overflow,bad_memory_access,illegal_instruction,exc_guard,objc_exception,main_thread_checker_violation,abort,watchdog_termination,user_force_quit,background_task_expired,data_protection_violation,code_signing_killed,jetsam_oom,cpu_resource_fatal,swiftui_update_loop,unclassified), with their rule IDs and confidence levels - dSYM discovery order – The nine-step chain, with the
XCSYM_FRAMEWORK_SCAN_TIMEOUTandXCSYM_DSYM_PATHSenvironment variables - Hang and unsupported input – The JSON rejections (
hang_report,unsupported_format,empty_bundle), so your assistant can route on the error field instead of scraping stderr - Troubleshooting table – Symptom, cause, and fix for the common exit codes, bundle errors, and slow symbolication
Documentation Scope
This page documents the xcsym-ref skill in the axiom-tools suite. xcsym is Axiom's bundled tool for analyzing a crash after it happens.
xcsym crashrejects hang reports (.ipsfiles withbug_type=298) by design; for a single hang, see Hang Diagnostics- For building an in-app crash reporter with the CrashReportExtension framework, see metrickit-ref
Key Concepts
- Start with
crash– It detects the format, finds dSYMs, runsatos, categorizes the crash, and emits JSON. Reach forverify,resolve, orfind-dsymonly whencrashreports a specific problem. - Exit codes carry the diagnosis – Codes 2, 3, 4, and 7 say why symbolication was incomplete, so read them before assuming the tool failed. Codes 5, 6, and 8 are real failures. Code 1 is a usage error, except from
crashgiven a hang or a non-fatal CPU or wakeups report: it then returns JSON saying where to take the report instead. - Size tiers protect context –
standard, the default, covers the full crashed thread. Usesummaryfor a quick look andfullonly when you need every thread. - Formats are detected automatically –
.ips, MetricKit JSON, and legacy.crashtext need no flags. In an.xccrashpointbundle, xcsym picks the most recently modified Filter and the raw.crashoverLocallySymbolicated/.
Related
- crash-analyzer – The agent that runs
xcsym crashand maps thepattern_tagto fix guidance - /axiom:analyze-crash – The command that analyzes a single crash file
- triage-analyzer and /axiom:triage – Fetch a Sentry or App Store Connect corpus and rank it with
xcsym triage - Production Triage – The corpus-triage workflow and the report format
triagereads - TestFlight Triage – TestFlight crash workflows that start with xcsym
- Console Capture (xclog) – The live counterpart: xclog captures logs while the app runs, while xcsym reads the crash afterward
- xclog-ref, xcprof-ref, and xcui-ref – References for the other bundled tools; the Tools overview covers axbuild and xcproject