Skip to content

When a run fails

In this chapter

  • Read what sapling diagnose checks 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.

Terminal
$ sapling diagnose
SAPLING 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 with

The 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.

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
# 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
})
Terminal
$ 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: ERROR
adam 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.

Terminal
$ sapling diagnose ADSL
SAPLING DIAGNOSE FAIL: 1 error(s), 0 warning(s); 0 of 1 program(s) ran to their end
scope: 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:

  1. The verdict: SAPLING DIAGNOSE FAIL, 1 error, and 0 of 1 program ran to its end.
  2. The program and its line: adsl.R:158, a generated program.
  3. The trace: the line belongs to a hook of the study, custom/adsl.R:3. Not the SAP, not the specification.
  4. Look first: the one place to read.
  5. Next: sapling fix.

When something fails, the agent works the fix loop:

  1. sapling diagnose: what failed, and its trace.
  2. The read-only tools of DataStep Studio for R to look at the data (dsr describe, dsr query, dsr freq).
  3. One proposal: a change of a SAP block, of a specification rule, or of a hook, marked drafted by: agent.
  4. The proposal is tested in a scratch copy of the study, never in the study itself.
  5. 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
Terminal
$ sapling diagnose T14_3_1
SAPLING DIAGNOSE CLEAN: 0 error(s), 0 warning(s); 1 of 1 program(s) ran to their end
scope: 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 with

One 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 diagnose reads 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.

Next: 18 · Before and after the unblinding →

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.