docs: explain execute() RUNNING-after-timeout behavior and how to debug stuck workflows#408
Merged
nthmost-orkes merged 3 commits intomainfrom Apr 28, 2026
Merged
Conversation
…ug stuck workflows Addresses conductor-oss/getting-started#53. Documents that status='RUNNING' from execute() is expected when wait_for_seconds (default 10s) expires before the workflow completes — a common surprise when a worker exception triggers a 60s retry delay. - Expand execute() docstring with the wait_for_seconds vs retryDelaySeconds gotcha, and a code snippet for inspecting failed task details programmatically - Add a FAQ entry in README.md covering the same scenario with a fix and debug steps - Add a "Debugging a stuck workflow" section in docs/WORKFLOW.md, and a callout box under "Execute workflow synchronously" explaining the timing relationship - Document that WorkflowRun.reason_for_incompletion is deprecated; recommend get_workflow(id, include_tasks=True) + task.reason_for_incompletion instead
Codecov Report✅ All modified and coverable lines are covered by tests.
... and 1 file with indirect coverage changes 🚀 New features to boost your workflow:
|
NicholasDCole
approved these changes
Apr 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
execute()docstring with thewait_for_secondsvsretryDelaySecondsgotcha, and a code snippet for inspecting failed task details programmaticallyREADME.mdcovering the same scenario with a concrete fix and debug stepsdocs/WORKFLOW.md, plus a callout box under "Execute workflow synchronously" explaining the timing relationshipWorkflowRun.reason_for_incompletionis deprecated and recommends the replacement pattern:get_workflow(id, include_tasks=True)+task.reason_for_incompletionUser impact: First-time users who see
status: RUNNINGwith empty output after their worker throws an exception have no documented path forward. Nothing explains thatwait_for_seconds=10(default) is shorter thanretryDelaySeconds=60(default), so the timeout fires while the retry is pending. These docs give users the vocabulary to understand what happened and the exact code to debug it.Closes conductor-oss/getting-started#53
Test plan
execute()docstring — covers the timing relationship and debugging patternwait_for_secondscall and theget_workflow()snippetdocs/WORKFLOW.mdsection — three-step debug guide with code examples🤖 Generated with Claude Code