When a run fails
In this chapter
- Read what
sapling diagnosechecks without running anything. - Follow a real failure to its trace: the program, the hook, the line.
- Know the fix loop: one proposal, tested in a scratch copy, accepted by a person.
- Time
- 20 minutes
- At the end you have
- a failed run read from its first cause to the line that made it, and the steps of the fix loop.
17.1 The idea: every failure has an address
Section titled “17.1 The idea: every failure has an address”A run can fail in a program that nobody wrote by hand. Then “the program failed” is not an answer. The question is: which block of the SAP, which rule of a specification, or which piece of custom code made the line that failed? Sapling keeps those links, so every failure comes with its trace.
sapling diagnose reads what the last run did, without running anything: each program’s log, each ADaM data set
against its specification (variables, types, lengths, labels, codelists), and, when you give one, each data set and
table against a reference.
$ sapling diagnoseSAPLING DIAGNOSE CLEAN: 0 error(s), 0 warning(s); 19 of 19 program(s) ran to their end
not checked: no reference for the ADaM data (sapling.yml reference.adam: <folder of .xpt>) no reference for the tables (sapling.yml reference.ard: <folder of the ARD .csv of a proven run>) no reference for the listings (sapling.yml reference.tlf: <folder of .lst>) no results of SAS (out/sas/ard): nothing to compare R withThe pilot ran clean: 19 of 19 programs ran to their end. The diagnosis also says what it did not check: there is no reference data, and no SAS run to compare R with.
17.2 A real failure
Section titled “17.2 A real failure”The template of Sapling is close, not always complete. A programmer adds what it cannot say in custom/, in files
Sapling never writes. Here, in a copy of the study, the agent drafted a hook for ADSL: a flag for patients aged 65 or
more. It has a typo: AGEN for AGE.
# custom/adsl.R: the programmer's code for ADSL. Sapling never writes this file.# drafted by: agent (2026-11-20)custom_step("adsl_age65", after = "ADSL.AGEGR1", function(data) { data$AGE65FL <- ifelse(data$AGEN >= 65, "Y", "N") data})$ sapling adam data ADSL adsl: BATCH: ERROR (3.1 s) ERROR .sapling/studies/pilot/programs/adam_sap/adsl.R log: .sapling/studies/pilot/programs/adam_sap/adsl.log (3 s) FIRST CAUSE: .sapling/studies/pilot/programs/adam_sap/adsl.R:158 (called at line 158): [SMA sma_custom_apply] custom/adsl.R hook_after("ADSL.AGEGR1"): replacement has 0 rows, data has 254 BATCH: ERRORadam data FAIL: 0 of 1 programs BATCH: CLEAN; out/adam/data (3.8 s)The program of ADSL stops. In R, data$AGEN of a column that does not exist is NULL, so the new column has 0 rows
for a data set of 254. The run prints the first cause, with the line of the generated program.
$ sapling diagnose ADSLSAPLING DIAGNOSE FAIL: 1 error(s), 0 warning(s); 0 of 1 program(s) ran to their endscope: ADSL
programs that failed: R .sapling/studies/pilot/programs/adam_sap/adsl.R:158 [SMA sma_custom_apply] custom/adsl.R hook_after("ADSL.AGEGR1"): replacement has 0 rows, data has 254
ERROR log:r:ADSL:error::158:[SMA sma_custom_apply] custom/ R .sapling/studies/pilot/programs/adam_sap/adsl.R:158: [SMA sma_custom_apply] custom/adsl.R hook_after("ADSL.AGEGR1"): replacement has 0 rows, data has 254 trace: hook custom/adsl.R:3 a hook of the study (custom/) look first: custom/adsl.R:3
not checked: no reference for the ADaM data (sapling.yml reference.adam: <folder of .xpt>)
next: sapling fix [OUTPUT|DATASET] (an agent finds the cause and proposes a correction of the SAP, a spec or a hook; you accept)Read it from the top:
- The verdict:
SAPLING DIAGNOSE FAIL, 1 error, and 0 of 1 program ran to its end. - The program and its line:
adsl.R:158, a generated program. - The trace: the line belongs to a hook of the study,
custom/adsl.R:3. Not the SAP, not the specification. - Look first: the one place to read.
- Next:
sapling fix.
17.3 The fix loop
Section titled “17.3 The fix loop”When something fails, the agent works the fix loop:
sapling diagnose: what failed, and its trace.- The read-only tools of DataStep Studio for R to look at the data (
dsr describe,dsr query,dsr freq). - One proposal: a change of a SAP block, of a specification rule, or of a hook, marked
drafted by: agent. - The proposal is tested in a scratch copy of the study, never in the study itself.
- A person accepts it:
sapling accept <id> --by NAME.
Here the proposal would be one line of the hook: data$AGE for data$AGEN. The copy of the study is then removed; the
pilot itself never had the hook.
Your turn 17.1 Diagnose one output
sapling diagnose takes an output or a data set. Diagnose only the primary table T14_3_1. How many programs does it
look at, and what does it not check?
Show the answer
$ sapling diagnose T14_3_1SAPLING DIAGNOSE CLEAN: 0 error(s), 0 warning(s); 1 of 1 program(s) ran to their endscope: T14_3_1
not checked: no reference for the tables (sapling.yml reference.ard: <folder of the ARD .csv of a proven run>) no reference for the listings (sapling.yml reference.tlf: <folder of .lst>) no results of SAS (out/sas/ard): nothing to compare R withOne program, and it ran to its end. It did not check the table against a reference (none is named in sapling.yml) or
against SAS (no SAS results exist).
What you learned
sapling diagnosereads the last run without running anything, and says what it did not check.- A failure comes with its trace: the generated line, the SAP block, the specification rule or the hook.
- The fix loop makes one proposal, tests it in a scratch copy, and waits for a person to accept it.
Found an error or have a question? Write to datastep.studio@gmail.com· The plan is written in Sapling; every R program runs in DataStep Studio for R.
Data: the CDISC pilot study (cdiscpilot01). The protocol as CDISC USDM from the CDISC 360i project (MIT licence); the SDTM data from the PhUSE scripts repository (MIT licence). Public example data: no real patient.
R is a project of the R Foundation. SAS is a registered trademark of SAS Institute Inc. CDISC, SDTM, ADaM and USDM are trademarks of the Clinical Data Interchange Standards Consortium. Claude is a trademark of Anthropic. This book is not affiliated with or endorsed by any of them.
© 2026 DataStep Labs. All rights reserved.