Workflow Issues
This guide covers common workflow problems and their solutions.
Workflow Not Running
Problem: Workflow is paused
Symptoms:
Workflow appears in list but never executes
No recent runs in workflow history
Solution:
Open the workflow in the dashboard
Check the workflow status indicator (top right)
If paused, click the "Resume" or "Enable" button
Verify the status changes to "Active"
Note: Workflows are automatically paused when they encounter repeated failures. Check the error history before resuming.
Problem: Schedule hasn't triggered yet
Symptoms:
Workflow is active but hasn't run at expected time
Recently created or modified workflow
Solution:
Scheduled workflows have a 0-15 minute execution window after their trigger time
Wait up to 15 minutes after the scheduled time before investigating
Check the "Next Run" timestamp in the workflow details to confirm when execution is expected
If the workflow was just created, the first run will occur at the next scheduled interval
Problem: Invalid schedule configuration
Symptoms:
Workflow shows "Invalid schedule" error
Schedule appears correct but workflow won't save
Solution:
Verify your cron expression is valid (use a cron validator tool)
Common mistakes:
- Using 7 fields instead of 5 (standard cron uses 5 fields)
- Using unsupported characters like L or W
- Specifying both day-of-month and day-of-week (use ? for one)
For simple schedules, use the visual schedule builder instead of raw cron expressions
Problem: Connection issues blocking execution
Symptoms:
Workflow fails immediately on start
Error mentions "connection" or "authentication"
Solution:
Navigate to Settings > Connections
Find the connection used by the workflow
Check the connection status indicator
If disconnected:
- Click "Reconnect" and complete the authentication flow
- For API key connections, verify the key hasn't been revoked
Test the connection using the "Test Connection" button
Re-run the workflow manually to verify the fix
Workflow Failing
Problem: Tool execution errors
Symptoms:
Workflow starts but fails during a specific step
Error message mentions a specific tool or action
Solution:
Open the workflow run details
Expand the failed step to see the full error message
Common causes:
- Permission denied: The connected account lacks required permissions
- Resource not found: The referenced item (file, project, task) was deleted or moved
- Rate limited: Too many requests to the external service
- Invalid input: The data passed to the tool doesn't match expected format
Fix the underlying issue and re-run the workflow
Problem: Approval timeout
Symptoms:
Workflow shows "Timed out waiting for approval"
Workflow was waiting for human approval
Solution:
Approval requests expire after the configured timeout (default: 24 hours)
To prevent future timeouts:
- Increase the approval timeout in workflow settings
- Set up approval notifications via email or Slack
- Assign approvals to a group rather than a single person
To re-run the workflow, click "Run Now" and provide approval when prompted
Problem: Connection credentials expired
Symptoms:
Workflow previously worked but now fails with authentication errors
Error mentions "token expired" or "invalid credentials"
Solution:
OAuth tokens typically expire after a set period
Navigate to Settings > Connections
Find the affected connection and click "Reconnect"
Complete the re-authentication flow
Re-run the failed workflow
Prevention: Enable automatic token refresh where available in connection settings.
Problem: How to find error details
Solution:
Go to the Workflows page
Click on the workflow name to open details
Select the "Runs" or "History" tab
Click on the failed run (indicated by red status)
Expand each step to see:
- Input data sent to the step
- Output or error returned
- Execution duration
- Raw error messages and stack traces
For detailed logs, click "View Full Logs" at the bottom of the run details
Unexpected Results
Problem: Prompt too vague
Symptoms:
AI produces results that don't match expectations
Output is generic or misses key requirements
Solution:
Review your workflow prompt
Add specific instructions:
- Bad: "Summarize the data"
- Good: "Summarize the sales data focusing on top 3 products by revenue, include percentage changes from last month"
Include examples of expected output format
Specify what to include AND what to exclude
Use structured output formats (JSON, bullet points) when precision matters
Problem: Wrong data being accessed
Symptoms:
Workflow processes incorrect files, projects, or records
Results reference unexpected items
Solution:
Check the data source configuration in your workflow
Verify filters and queries are correct:
- Date ranges may have shifted
- Dynamic filters may resolve differently than expected
Use explicit IDs instead of names when possible (names can be duplicated)
Add a preview step to verify data before processing
Check if the source data has been reorganized or renamed
Problem: AI misunderstanding intent
Symptoms:
AI takes actions you didn't intend
Interpretation of instructions differs from expectations
Solution:
Be explicit about what actions are allowed:
- Bad: "Update the task if needed"
- Good: "Update only the task description field. Do not modify status, assignee, or due date"
Add constraints: "Only process items from the last 7 days"
Include negative instructions: "Do not delete any records"
Break complex workflows into smaller, focused steps
Use the workflow test mode to preview AI decisions before enabling
Problem: How to improve prompts
Solution:
Start with the end goal clearly stated
Provide context about the data being processed
Define the exact output format expected
Include 1-2 examples of correct behavior
Add boundary conditions and edge case handling
Test with varied inputs before deploying
Review actual run outputs and iterate on the prompt
Template:
Goal: [What should be accomplished]
Context: [Background information the AI needs]
Input: [Description of incoming data]
Output: [Exact format and fields expected]
Constraints: [What NOT to do, limits, boundaries]
Example: [Sample input -> expected output]
Approval Not Working
Problem: Workflow stuck waiting for approval
Symptoms:
Workflow status shows "Waiting for approval"
No progress for extended period
Solution:
Check if the approval request was sent:
- View the workflow run details
- Confirm the approval step executed
Verify you have access to approve:
- Check if approval is assigned to you or your team
- Confirm you have the required role/permissions
Look for the approval request:
- Check your Zenmako notifications
- Check email spam folder
- Check connected Slack channel
Approve or reject from the workflow run details page
Problem: Missed approval notification
Symptoms:
Approval request exists but you weren't notified
Found pending approval by accident
Solution:
Check notification settings in your profile
Verify email address is correct and verified
If using Slack notifications:
- Confirm the Slack connection is active
- Check you're in the designated notification channel
Set up multiple notification channels for redundancy
Consider adding a secondary approver to receive notifications
Problem: How to cancel pending approvals
Solution:
Navigate to the workflow run that's waiting for approval
Click "Cancel Run" or "Abort" button
Confirm the cancellation
The workflow will be marked as cancelled and release any held resources
Alternative - Reject the approval:
Open the pending approval request
Click "Reject" instead of "Approve"
Optionally add a rejection reason
The workflow will proceed to its rejection handler (if configured) or terminate
Schedule Issues
Problem: Wrong timezone
Symptoms:
Workflow runs at unexpected hours
Schedule appears correct but timing is off
Solution:
Check your account timezone in Settings > Profile
Check the workflow's timezone setting (may override account default)
Zenmako displays all times in your configured timezone
If times still seem wrong:
- Verify your browser/system timezone matches your expected timezone
- Remember that UTC doesn't observe daylight saving time
Update the timezone setting and save the workflow
Problem: Runs at unexpected times
Symptoms:
Workflow runs more or less frequently than expected
Run times don't match the schedule
Solution:
Review the cron expression carefully:
- 0 9 = 9:00 AM daily
- 0 9 1-5 = 9:00 AM weekdays only
- /15 = Every 15 minutes (not every 15th minute)
Check for multiple schedules on the same workflow
Verify no other workflow or automation is triggering this workflow
Check the "Trigger" column in run history to see what initiated each run
Use the schedule preview feature to see upcoming run times
Problem: Cron expression errors
Symptoms:
"Invalid cron expression" error when saving
Schedule doesn't behave as documented
Solution:
Common cron mistakes and fixes:
0 9 | 6 fields (seconds included) | 0 9 (5 fields) |
0 9 1 1 | Both day-of-month and day-of-week | Pick one, use |
0 25 | Invalid hour (0-23 only) | 0 23 |
0 9 32 | Invalid day (1-31 only) | 0 9 28 |
Cron field reference:
Minute (0-59)
Hour (0-23)
Day of month (1-31)
Month (1-12)
Day of week (0-6, where 0=Sunday)
Examples:
Daily at 9 AM: 0 9
Every Monday at 8 AM: 0 8 1
First of every month at midnight: 0 0 1
Every 6 hours: 0 /6
Weekdays at 9 AM and 5 PM: 0 9,17 1-5
Getting Help
If your issue isn't covered here:
Check the workflow run logs for detailed error messages
Review the specific tool or connection documentation
Search the knowledge base for your error message
Contact support with:
- Workflow ID
- Run ID of the failed execution
- Steps to reproduce the issue
- Expected vs actual behavior
Zenmako