Debug API and backend workflows in Bubble using Server Logs to inspect execution details, the Scheduler tab to check queued workflows, and logging steps that write intermediate values to a Debug data type. Since backend workflows lack a visual debugger, test API calls in Postman first, add logging actions to trace data flow, and check for common issues like Privacy Rule conflicts and parameter mismatches.
Debug API Workflows in Bubble
Backend and API workflows in Bubble are harder to debug than frontend workflows because they lack a visual debugger. This tutorial shows you practical techniques for finding and fixing issues in backend workflows, scheduled tasks, and API Connector calls.
Prerequisites
- A Bubble app with backend workflows configured
- Access to Server Logs (paid plans have longer retention)
- Postman or similar API testing tool (optional but recommended)
- Understanding of backend vs frontend workflows
Step-by-step guide
Check Server Logs for Error Details
Check Server Logs for Error Details
Go to Logs tab → Server Logs. Filter by time range around when the issue occurred. Look for red error entries. Click on an error to see: which workflow or action failed, the error message, the data involved, and workload units consumed. Common errors: 'Workflow not found' (name mismatch or not deployed), 'Permission denied' (Privacy Rules blocking), and timeout errors.
Pro tip: Free plans retain Server Logs for only 6 hours. Check logs promptly after testing, or upgrade for longer retention.
Expected result: You can identify which workflow action failed and the error message.
Add Logging Steps to Backend Workflows
Add Logging Steps to Backend Workflows
Create a Data Type called 'DebugLog' with fields: workflow_name (text), step (text), data_value (text), timestamp (date). In your backend workflow, add 'Create a new DebugLog' actions between steps — log the workflow name, current step number, and the value of key data at that point. After running the workflow, check the DebugLog entries in Data tab → App data to trace the execution.
Expected result: A trail of log entries showing exactly which steps executed and what data was available at each point.
Test API Calls in Postman First
Test API Calls in Postman First
Before configuring an API call in Bubble's API Connector, test it in Postman. Set the URL, method, headers (including authentication), and body. Verify the response structure. Once it works in Postman, replicate the exact same configuration in Bubble. This isolates whether issues are with the API itself or Bubble's configuration.
Expected result: API calls work in Postman, confirming the endpoint and authentication are correct before Bubble configuration.
Check the Scheduler Tab for Queued Workflows
Check the Scheduler Tab for Queued Workflows
Go to Logs tab → Scheduler. This shows all scheduled API workflows — pending, running, and completed. Check that your workflow appears in the queue at the expected time. If a workflow is not in the queue, the scheduling action may have failed or the workflow name may not match. Completed workflows show their status (success or error).
Expected result: You can verify that workflows are properly queued and track their execution status.
Diagnose Common Backend Workflow Issues
Diagnose Common Backend Workflow Issues
Common issues and fixes: (1) 'Workflow not found' — ensure the workflow is deployed (push to development/live) and the name matches exactly (case-sensitive). (2) Privacy Rules blocking — check 'Ignore privacy rules' on the workflow. (3) Parameter type mismatch — verify parameter types match between the scheduling action and the workflow definition. (4) Timeout — backend workflows have a time limit; break long operations into smaller scheduled chunks.
Expected result: You can diagnose and fix the most common backend workflow failures.
Complete working example
1DEBUGGING TOOLKIT:231. DATA TYPE: DebugLog4 - workflow_name (text)5 - step (text)6 - data_value (text)7 - timestamp (date, default: Current date/time)8 - error_message (text)9102. LOGGING PATTERN IN BACKEND WORKFLOWS:11 Step 1: Create DebugLog (workflow='process-order', step='1-start', data=parameter values)12 Step 2: [Actual action]13 Step 3: Create DebugLog (step='2-after-action', data=Result of step 2)14 Step 4: [Next action]15 Step 5: Create DebugLog (step='3-complete', data='success')16173. ERROR HANDLING PATTERN:18 Enable 'Include errors in response' on API Connector calls19 Check response for errors before proceeding20 Log errors to DebugLog with error_message field21224. COMMON ERRORS:23 - 404 Workflow not found → Deploy, check name spelling24 - Privacy rule violation → Check 'Ignore privacy rules'25 - Parameter mismatch → Verify types in workflow definition26 - Timeout → Break into smaller scheduled chunks27285. TOOLS:29 - Server Logs: execution details, errors, WU usage30 - Scheduler: queued workflow status31 - DebugLog data type: custom trace data32 - Postman: test API calls before Bubble configCommon mistakes when debugging API workflows in Bubble.io: Step-by-Step Guide
Why it's a problem: Not deploying workflows before testing
How to avoid: After creating or modifying a backend workflow, deploy to the environment you are testing in.
Why it's a problem: Forgetting to check 'Ignore privacy rules' when needed
How to avoid: Check 'Ignore privacy rules when running this workflow' on the backend workflow. Also check each individual action step that needs elevated access.
Why it's a problem: Not cleaning up DebugLog entries after debugging
How to avoid: Create a scheduled cleanup workflow that deletes DebugLog entries older than 7 days, or manually delete them after resolving the issue.
Best practices
- Add temporary DebugLog entries to trace execution, then remove them after fixing the issue.
- Test API calls in Postman before configuring them in Bubble's API Connector.
- Check Server Logs immediately after testing (free plan retains only 6 hours).
- Use meaningful step names in DebugLog entries for easy tracing.
- Break long backend workflows into smaller steps for easier debugging.
- Include error messages from API responses in your DebugLog entries.
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I have a backend workflow in Bubble.io that is not executing properly. I see '404 Workflow not found' in Server Logs. The workflow is called 'process-order' and takes an order_id parameter. How do I debug this?
Add debugging to my backend workflows. Create a DebugLog data type and add logging steps between each action in the process-order workflow. Log parameter values, search results, and action outcomes.
Frequently asked questions
Why does the Step-by-step Debugger not work for backend workflows?
The Debugger only works for frontend workflows that run in the browser. Backend workflows run server-side with no browser context. Use Server Logs and DebugLog entries instead.
How do I see what data a backend workflow received?
Add a DebugLog entry as the first action in the workflow that logs all parameter values. Check the entry in Data tab → App data after the workflow runs.
Can I test a backend workflow manually?
Yes. If exposed as a public API, call it directly with Postman using the URL and parameters. Or create a test button on a page that schedules the workflow for 'Current date/time' (immediate execution).
What does 'Include errors in response' do in API Connector?
It prevents workflow failure when an API call returns an error. Instead, the error is included in the response data, allowing you to handle it in subsequent workflow steps.
How do I handle intermittent failures?
Add retry logic: schedule the workflow again with a delay if it fails. Track retry count to prevent infinite retries. For complex debugging scenarios, RapidDev can help diagnose and resolve persistent backend issues.
Are there third-party debugging tools for Bubble?
Tools like Flusk (now part of Bubble's Security Dashboard) scan for issues. Browser DevTools show network requests. BDK (Bubble Dev Kit) browser extension helps with editor debugging.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation