Human Input Node (HITL)#

The Human Input node (HITL — Human-in-the-Loop) pauses a Dify workflow or chatflow at a designated point, presents an interactive form to an operator, and resumes execution based on the operator's response. It works in both Chatflow and Workflow app types and can be used inside Loop and Iteration container nodes 1.

The form supports configurable field types (Paragraph, Select, File, FileList), user action buttons that route execution to different branches, delivery via WebApp or Email, and node-level and global timeouts. It was introduced in PR #32060 1.

Backend Implementation#

Core Node Module#

All node-specific logic lives in api/core/workflow/nodes/human_input/ 1:

Architecture boundary: graphon owns generic pause/resume infrastructure (HITLContext, HITLDecision, PauseRequested); Dify owns workflow-specific form schema, field types, timeout semantics, and DifyHITLCallback 1.

Timeout Semantics#

Two distinct layers 1:

• Node-level (TIMEOUT): returns Expired(selected_handle="__timeout"), routing to the timeout branch.
• Global expiry (EXPIRED or WAITING + global deadline passed): treated as invalid, raises AssertionError. Global deadline = created_at + HUMAN_INPUT_GLOBAL_TIMEOUT_SECONDS.

Service Layer#

api/services/human_input_service.py exposes 1:

• get_form_definition_by_token() / get_form_definition_by_token_for_console() — form retrieval for WebApp vs. console recipients
• submit_form_by_token() — validates, marks submitted, enqueues resume
• enqueue_resume() — dispatches resume_app_execution Celery task on workflow_based_app_execution queue

Variable Template Rendering#

DifyHITLCallback.render_form_content_before_submission() resolves {{#...#}} placeholders via convert_template() before pause. The frontend relies entirely on the pre-rendered rendered_content stored in the DB — it does not resolve variables client-side 1.

Frontend Implementation#

Component Hierarchy#

Forms appear in two rendering contexts that share inner components 1:

HumanInputFormList ← active (unsubmitted) forms
  └─ ContentWrapper ← card with node icon + expand toggle
       └─ UnsubmittedHumanInputContent

HumanInputFilledFormList ← completed (submitted) forms
  └─ ContentWrapper (expanded=true)
       └─ SubmittedHumanInputContent

The same ContentWrapper 2 is used in both the chat answer path (web/app/components/base/chat/chat/answer/) and the workflow panel path (web/app/components/workflow/panel/).

Key Frontend Files#

isResponding and Chat Input State#

useChat in hooks.ts drives the chat input's enabled/disabled state through isResponding 5:

• onWorkflowStarted → sets isResponding = true 6
• onWorkflowPaused → sets isResponding = false 7
• onHumanInputFormFilled → sets isResponding = true when form is submitted and execution resumes 8

Both HumanInputFormList variants filter to display_in_ui === true before rendering 9. Per-node showEmailTip, isEmailDebugMode, and showDebugModeTip flags are computed from delivery_methods config to show contextual hints to the operator 10.

Known Issues and Version-Specific Fixes#

1. No reply after Conditional Branch (≤1.15.0) — Fixed in PR #38540#

Symptom: After a Human Input pause in a chatflow with an upstream conditional branch, the downstream Answer node ran successfully but no message appeared in the chat UI 1.

Root cause: On resume, iter_dify_graph_engine_events() instantiated a fresh ResponseStreamFilter with no record of edges traversed before the pause. The Answer node's paths_map entry never emptied, permanently blocking streaming 11.

Fix: PauseStatePersistenceLayer now serializes ResponseStreamFilter via dumps() on every GraphRunPausedEvent and restores it via loads() on resume 11. Triggers: upstream if-else branch, a second Human Input in the same run, an Answer node that already streamed, or a variable written before the pause referenced post-resume.

2. Chat input disabled after Human Input completion (≤1.16.1) — Fixed in PR #38992 + PR #39485#

Symptom: After submitting a Human Input form in a published Chatflow WebApp, the chat input box remained permanently disabled (greyed out); a page refresh was required 12.

Root cause (backend): WorkflowAppQueueManager did not include QueueWorkflowPausedEvent in its terminal event set. When the SSE stream closed after pause, the listen() finally block called _abort_execution(), writing a Redis stop flag keyed on task_id. The resumed run inherited that flag and aborted, preventing delivery of the workflow_started event that would re-enable the input 12 13.

Fix: PR #39485 14 adds QueueWorkflowPausedEvent to the terminal set in WorkflowAppQueueManager, treating pause as ending only the current listener segment. PR #38992 15 fixes the frontend by adding handleResponding(true) in onWorkflowStarted so that isResponding is restored when a paused workflow resumes.

Why Chatflow vs. Workflow differed: The advanced-chat pipeline already published QueueAdvancedChatMessageEndEvent on pause (which IS in the terminal set), so Chatflow was less vulnerable to the backend abort — but both were affected by the frontend isResponding regression 12.

3. Resume aborts with "Stopped by user" — Fixed progressively in PR #39813 and PR #40905#

Symptom: Clicking Confirm on the Human Input form caused the resumed run to abort with "Stopped by user" 1 16.

Root cause: A resumed workflow reuses the paused run's task_id. Both cancellation channels — the generate_task_stopped:{task_id} Redis flag (TTL 600 s) and queued AbortCommand messages in the workflow:{task_id}:commands channel (TTL 3600 s) — are keyed by task_id. Signals written during the pause persist until resume 1.

Fix — PR #39813 17: Introduced AppExecutionCoordinator (api/core/app/apps/execution_coordinator.py) to decouple the response-listener lifecycle from execution cancellation. Listener detachment is now an observation, not an abort trigger. The coordinator models PAUSED vs. TERMINAL states explicitly.

Fix — PR #40905 18: Added clear_app_task_cancellation_signals(), called in _resume_app_execution() before any engine starts. It deletes the Redis stop flag and drains queued AbortCommand messages for the task_id, so no stale signals from before the pause can abort the resumed attempt. Both Workflow and Chatflow share this resume path.

4. Raw {{#...#}} placeholders after page refresh#

After a page refresh during a pending pause, the form may display unresolved variable placeholders. Root cause: render_form_content_before_submission() either failed to call convert_template() at pause time, or the API returned raw form_content instead of rendered_content 1.

5. Pointer event handling for chat input (≤1.16.0) — Fixed in PR #38385 and PR #38510#

The chat footer and inner layout were intercepting pointer events and blocking interactions. PR #38385 19 applied pointer-events-none to the container, restoring events only on interactive controls. PR #38510 20 followed up with a further refactor of the chat footer pointer-events pass-through.

Key Source Files Quick Reference#