Running & Debugging Flows

This guide covers how to run your flows, read execution logs, and troubleshoot common issues.

Ways to Run a Flow

1. Automatic (Active Flow)

Toggle the Active switch on your flow. Once active, the flow runs automatically based on its trigger:

• Schedule triggers are checked every 60 seconds by the built-in scheduler. Cron-based schedules (daily, weekly, monthly) fire at the configured time. Date-field schedules check your contact table for matching dates each day.
• Incoming message triggers fire immediately when a WhatsApp message is received on the connected account.

2. Run Now

Click Run Now to execute the flow immediately. This works regardless of the trigger type or whether the flow is active. Useful for testing or running a flow on demand.

3. Dry Run

Toggle Dry Run mode before clicking Run Now. The flow runs through all its logic -- AI calls, filters, loops, conditions -- but does not send any real messages or emails. Send actions are logged with a "would send" note showing the recipient and message content.

Dry run is the safest way to test a new or modified flow before going live.

Execution Status

Every flow run gets an execution record with one of these statuses:

Status	Meaning
running	The flow is currently executing
completed	The flow finished successfully -- all nodes ran without errors
completed_with_errors	The flow finished but some messages failed to send (e.g., invalid phone numbers, disconnected account)
failed	The flow stopped due to a critical error (e.g., no trigger node found, invalid flow JSON, max depth exceeded)
cancelled	The flow was manually stopped

Viewing Execution Logs

There are two ways to view logs:

1. From the flow editor -- Click the clock icon on a flow to see its recent executions.
2. From the Logs page -- View execution history across all flows.

Step-by-Step Log

Each execution contains a detailed step-by-step log. Every node that ran is recorded with:

• Status -- completed, failed, skipped, or running
• Timing -- how long the node took to execute
• Input -- the configuration the node received
• Output -- the data the node produced
• Error message -- what went wrong (if the node failed)

For AI nodes, the log also shows:

• The resolved system prompt (with all variables filled in)
• The resolved user prompt
• The AI reply text
• Token usage (how many input/output tokens were consumed)

Click any step row to expand it and see the full details.

Deduplication: Skip If Recent

The Send Message and Send Template nodes have a "Skip if recently sent" option. When enabled, the node checks whether this flow has already sent a message to the same phone number within the last X hours. If it has, the send is skipped.

This prevents duplicate messages when a scheduled flow runs multiple times or when you are testing. Common settings:

• 24 hours -- for daily reminders
• 168 hours (7 days) -- for weekly follow-ups
• 720 hours (30 days) -- for monthly campaigns

Skipped sends show as "skipped" in the execution log with the reason "skip_if_recent."

Rate Limits

ReplyWolf has built-in rate limiting to protect your WhatsApp account:

• Daily limit -- A configurable maximum number of messages per day per account. Once reached, all sends for that account are paused until the next day.
• Delay between messages -- A configurable pause between consecutive messages (capped at 55 seconds). This prevents sending a burst of messages all at once.

Rate limits are configured in the account settings. When a send hits the daily limit, it fails with the error "Daily limit reached."

Scheduler Details

The built-in scheduler runs every 60 seconds and checks all active flows with schedule triggers:

• For cron-based schedules, it checks whether the cron expression's next fire time has passed since the last execution.
• For date-field schedules, it scans the linked contact table for rows where the date column matches today, then runs the flow for those contacts at the configured time.

The scheduler also handles housekeeping:

• Cleans up execution history older than 30 days
• Removes expired deduplication records

If a flow is already executing when the next tick arrives, the scheduler skips it to prevent double execution.

Common Issues and Solutions

"No contacts matched"

Cause: A date-field trigger or filter node found zero matching contacts.

Fix: Check that your contact table has data in the date column, that the date format is correct (YYYY-MM-DD works best), and that your filter conditions are not too restrictive. Run the flow with dry run to see what the filter is doing.

"AI error" or "AI generation failed"

Cause: The AI provider returned an error. Common reasons include an invalid or expired API key, a rate limit from the AI provider, or a network issue.

Fix: Go to Settings and verify your AI API key is correct. Check that your AI provider account has available credits. AI nodes automatically retry up to 2 times with backoff, but authentication errors (401/403) are not retried.

"Account not connected"

Cause: The WhatsApp account linked to the flow is not currently connected.

Fix: Go to the Accounts page and reconnect the account by scanning the QR code. Make sure the account shows a "Connected" status before running the flow.

"Daily limit reached"

Cause: The account has hit its configured daily message limit.

Fix: Wait until the next day when the counter resets, or increase the daily limit in account settings. Be careful not to set it too high -- WhatsApp may flag accounts that send too many messages.

"Contact has opted out"

Cause: The contact has been marked as opted out in the chat view.

Fix: This is working as intended. Opted-out contacts are protected from receiving automated messages. If the contact wants to receive messages again, remove the opt-out flag from their conversation.

"Empty message body"

Cause: The message template resolved to an empty string, usually because the variables used in the template were all empty.

Fix: Check that your contact data has values in the fields you are referencing. Use the default filter to provide fallback text: {{name | default(Customer)}}.

"Max execution depth exceeded (500 nodes)"

Cause: The flow executed more than 500 node steps in a single run. This is a safety limit to prevent runaway flows.

Fix: Check for unintended loops or very large contact tables. Consider breaking the flow into smaller flows or adding filters to reduce the number of contacts processed.

Slow execution

Each node has a 60-second timeout. If a single node (like an AI call or API request) takes longer than 60 seconds, it times out and fails. Wait delays are capped at 55 seconds per node to stay within this limit.

The entire scheduler tick has a 5-minute timeout. If all scheduled flows combined take longer than 5 minutes, the tick is cancelled to prevent blocking.