docs: Added guide on debugging workflows by mrmattuschka · Pull Request #4029 · snakemake/snakemake

mrmattuschka · 2026-03-10T14:20:42Z

Closes #4013 .

Added a docs page on debugging workflows:

log file locations
faster DAG resolution
interactive debugging
preserving script rule wrapper scripts

QC

The PR contains a test case for the changes or the changes are already covered by an existing test case.
Not applicable - only documentation affected
The documentation (docs/) is updated to reflect the changes or this is not necessary (e.g. if the change does neither modify the language nor the behavior or functionalities of Snakemake).

Summary by CodeRabbit

Documentation
- Added a comprehensive debugging guide for workflows: log file usage and per-job logs across executors, redirecting STDERR in Python and R (with examples), enabling R backtraces, tips to speed DAG resolution by targeting outputs, interactive VS Code debugging setup (including launch configuration and breakpoints), guidance for debugging whole workflows vs individual jobs, and notes on preserving wrapper scripts.
- Added an index entry linking the new debugging guide from the main documentation.

Added a docs page on debugging workflows: - log file locations - faster DAG resolution - interactive debugging ### QC  * [ ] The PR contains a test case for the changes or the changes are already covered by an existing test case. **Not applicable - only documentation affected** * [X] The documentation (`docs/`) is updated to reflect the changes or this is not necessary (e.g. if the change does neither modify the language nor the behavior or functionalities of Snakemake).

coderabbitai · 2026-03-10T14:21:01Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 8fa09d21-aab7-427e-9550-b3baea613f78

📥 Commits

Reviewing files that changed from the base of the PR and between b19f93c and 16ade14.

📒 Files selected for processing (1)

docs/index.rst

✅ Files skipped from review due to trivial changes (1)

docs/index.rst

📝 Walkthrough

Walkthrough

Adds a new documentation page describing debugging workflows for Snakemake and registers it in the docs index under "Defining workflows". The page covers log locations, per-job logs, STDERR redirection, R backtraces, VS Code interactive debugging, breakpoints, and wrapper-script preservation.

Changes

Cohort / File(s)	Summary
Documentation Index `docs/index.rst`	Added `snakefiles/debugging_workflows` to the toctree under "Defining workflows".
Debugging Guide `docs/snakefiles/debugging_workflows.rst`	New documentation file detailing log file locations, per-job logs for executors, STDERR redirection examples (Python, R), enabling R backtraces, DAG-targeting for faster resolution, VS Code interactive debugging setup with JSON launch config, breakpoint instructions, debugging scope notes, and `--skip-script-cleanup` guidance.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding a guide on debugging workflows.
Description check	✅ Passed	The PR description covers main changes, references the linked issue, and completes the required QC checklist section.
Linked Issues check	✅ Passed	The PR comprehensively addresses issue `#4013` by documenting debugging tools, log file locations, and providing practical guidance as requested.
Out of Scope Changes check	✅ Passed	All changes are documentation additions directly related to the debugging workflows guide objective stated in issue `#4013`.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/how-to-guide-for-debugging

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Added section on preserving wrapper scripts ### QC  * [ ] The PR contains a test case for the changes or the changes are already covered by an existing test case. **Docs only** * [x] The documentation (`docs/`) is updated to reflect the changes or this is not necessary (e.g. if the change does neither modify the language nor the behavior or functionalities of Snakemake).

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/snakefiles/debugging_workflows.rst`:
- Line 77: Docs have small typos: remove the duplicated word "with" in the
sentence containing "Visual Studio Code <https://code.visualstudio.com/> editor
comes with with", remove the extra period in the phrase "variables.." (make it
"variables."), and replace the incorrect "library() s" token with "library()" or
"library() calls" for correct wording; update those three occurrences (the
fragments "with with", "variables..", and "library() s") accordingly in the
documentation.
- Around line 100-111: The VS Code launch snippet incorrectly sets "program":
"-m" and passes "snakemake" in the "args" list; update the launch configuration
to use "module": "snakemake" (remove the "program" entry) and remove "snakemake"
from the "args" array so the Snakemake module is launched via the "module"
field; ensure other args like "--debug", "--cores", "--nolock", "--forceall",
and "--executor" remain in "args" and keep "python":
"${command:python.interpreterPath}" as-is.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bd277526-3cb0-4990-a784-f96bc2cd0cc8

📥 Commits

Reviewing files that changed from the base of the PR and between e7bcd63 and 0214ba5.

📒 Files selected for processing (2)

docs/index.rst
docs/snakefiles/debugging_workflows.rst

docs/snakefiles/debugging_workflows.rst

coderabbitai

♻️ Duplicate comments (1)

docs/snakefiles/debugging_workflows.rst (1)

150-150: ⚠️ Potential issue | 🟡 Minor

Fix awkward phrasing: "library() s".

The phrasing "library() s" is awkward. Consider rephrasing to one of:

"load all the libraries you need"
"load all the library() calls you need"
"call all the library() functions you need"

📝 Suggested fix

-Start an interactive R session and load all the ``library()`` s that you need for the script. Then you can load the full workspace and interactively explore / debug what's going on:
+Start an interactive R session and load all the libraries you need for the script. Then you can load the full workspace and interactively explore / debug what's going on:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/snakefiles/debugging_workflows.rst` at line 150, The sentence "load all
the ``library()`` s that you need" uses awkward spacing and pluralization;
update the wording in docs/snakefiles/debugging_workflows.rst to a clearer
phrase such as "load all the libraries you need", "call all the `library()`
functions you need", or "load all the `library()` calls you need" and ensure the
inline code formatting remains for `library()` where appropriate (reference
symbol: library()).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@docs/snakefiles/debugging_workflows.rst`:
- Line 150: The sentence "load all the ``library()`` s that you need" uses
awkward spacing and pluralization; update the wording in
docs/snakefiles/debugging_workflows.rst to a clearer phrase such as "load all
the libraries you need", "call all the `library()` functions you need", or "load
all the `library()` calls you need" and ensure the inline code formatting
remains for `library()` where appropriate (reference symbol: library()).

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 520eef59-a74f-4692-959c-2ff796e0b822

📥 Commits

Reviewing files that changed from the base of the PR and between 8f4af4e and b19f93c.

📒 Files selected for processing (2)

docs/index.rst
docs/snakefiles/debugging_workflows.rst

🚧 Files skipped from review as they are similar to previous changes (1)

docs/index.rst

dlaehnemann

This looks good, thanks for taking the time to bring this together. I mostly have some minor suggestions, and on thing that will especially make further reviewing and editing easier:

We generally try to have one sentence per line. That way the diffs are easier to read.

But only apply that once you've gone through the suggestions, as they might otherwise not be rendered correctly any more...

dlaehnemann · 2026-03-30T13:41:38Z

docs/snakefiles/debugging_workflows.rst

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Depending on the executor you are using, additional log files may be generated for each job. 
+For the location thereof, please refer to the documentation of the respective executor.


I would add a linkout to the plugin catalog, here:

Suggested change

For the location thereof, please refer to the documentation of the respective executor.

For the location thereof, please refer to the `documentation of the respective executor pluging <https://snakemake.github.io/snakemake-plugin-catalog/>`_.

dlaehnemann · 2026-03-30T13:49:17Z

docs/snakefiles/debugging_workflows.rst

+
+To now debug your workflow:
+
+1. Add breakpoints to your Snakefile by adding ``breakpoint()`` statements wherever you want to halt execution to inspect the state of the workflow.


Maybe add an example here, for example using the breakpoint in the onerror handler, linking out to the respective docs in the test:
https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#onstart-onsuccess-and-onerror-handlers

You can use the :ref: syntax and the hyperlink target snakefiles-job_lifetime_handlers.

dlaehnemann · 2026-03-30T13:50:54Z

docs/snakefiles/debugging_workflows.rst

+
+**For R scripts / run blocks:**
+
+You can save the entire current state of a workspace in R, for debugging you can insert this line right before some code triggers an error:


Suggested change

You can save the entire current state of a workspace in R, for debugging you can insert this line right before some code triggers an error:

You can save the entire current state of a workspace in R for debugging.

Insert this line right before some code triggers an error:

dlaehnemann · 2026-03-30T13:52:57Z

docs/snakefiles/debugging_workflows.rst

+    save.image(file = "my_dump.RData")
+
+
+Start an interactive R session and load all the ``library()`` s that you need for the script. Then you can load the full workspace and interactively explore / debug what's going on:


Suggested change

Start an interactive R session and load all the ``library()`` s that you need for the script. Then you can load the full workspace and interactively explore / debug what's going on:

Activate the conda environment that the rule uses (you can find this in the logging output, with a statement starting with ``Activating conda environment: ``) and start an interactive R session.

In this session, load all the ``library()`` s that you need for the script.

Then you can load the full workspace and interactively explore / debug what's going on:

mrmattuschka linked an issue Mar 10, 2026 that may be closed by this pull request

docs: How-to guide for debugging #4013

Open

mrmattuschka added 4 commits March 12, 2026 12:15

Merge branch 'main' into docs/how-to-guide-for-debugging

21885f5

Merge branch 'main' into docs/how-to-guide-for-debugging

98ae662

Merge branch 'main' into docs/how-to-guide-for-debugging

0214ba5

mrmattuschka marked this pull request as ready for review March 13, 2026 11:27

mrmattuschka requested a review from johanneskoester as a code owner March 13, 2026 11:27

coderabbitai bot reviewed Mar 13, 2026

View reviewed changes

docs/snakefiles/debugging_workflows.rst Outdated Show resolved Hide resolved

docs/snakefiles/debugging_workflows.rst Show resolved Hide resolved

typo

8f4af4e

mrmattuschka mentioned this pull request Mar 13, 2026

docs: tracking issue for documentation improvements at the Snakemake Hackathon 2026 #4011

Open

15 tasks

mrmattuschka and others added 2 commits March 13, 2026 14:39

Formatting

a9ab034

Merge branch 'main' into docs/how-to-guide-for-debugging

b19f93c

coderabbitai bot reviewed Mar 13, 2026

View reviewed changes

mrmattuschka requested a review from dlaehnemann March 13, 2026 14:46

Merge branch 'main' into docs/how-to-guide-for-debugging

7ef73a1

mrmattuschka changed the title ~~docs: Added guide on debugging workflows (#4028)~~ docs: Added guide on debugging workflows Mar 17, 2026

Merge branch 'main' into docs/how-to-guide-for-debugging

16ade14

dlaehnemann requested changes Mar 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Added guide on debugging workflows#4029

docs: Added guide on debugging workflows#4029
mrmattuschka wants to merge 10 commits intomainfrom
docs/how-to-guide-for-debugging

mrmattuschka commented Mar 10, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Mar 10, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Uh oh!

coderabbitai bot left a comment

Uh oh!

dlaehnemann left a comment

Uh oh!

dlaehnemann Mar 30, 2026

Uh oh!

dlaehnemann Mar 30, 2026

Uh oh!

dlaehnemann Mar 30, 2026

Uh oh!

dlaehnemann Mar 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	For the location thereof, please refer to the documentation of the respective executor.
	For the location thereof, please refer to the `documentation of the respective executor pluging <https://snakemake.github.io/snakemake-plugin-catalog/>`_.


		To now debug your workflow:

		1. Add breakpoints to your Snakefile by adding ``breakpoint()`` statements wherever you want to halt execution to inspect the state of the workflow.


		For R scripts / run blocks:

		You can save the entire current state of a workspace in R, for debugging you can insert this line right before some code triggers an error:

	You can save the entire current state of a workspace in R, for debugging you can insert this line right before some code triggers an error:
	You can save the entire current state of a workspace in R for debugging.
	Insert this line right before some code triggers an error:

		save.image(file = "my_dump.RData")


		Start an interactive R session and load all the ``library()`` s that you need for the script. Then you can load the full workspace and interactively explore / debug what's going on:

Conversation

mrmattuschka commented Mar 10, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

QC

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

dlaehnemann left a comment

Choose a reason for hiding this comment

Uh oh!

dlaehnemann Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

dlaehnemann Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

dlaehnemann Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

dlaehnemann Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mrmattuschka commented Mar 10, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Mar 10, 2026 •

edited

Loading