Troubleshooting
Common issues, solutions, and debugging tips for Record Flow
Installation Issues
macOS: "App is damaged and can't be opened"
Common on macOS
This happens because the app is not signed with an Apple Developer certificate yet.
Solution:
- 1. Move Record Flow to your Applications folder
- 2. Open Terminal
- 3. Run this command:
xattr -c /Applications/Record\ Flow.app
This removes the quarantine attribute from the app.
Linux: Browser Doesn't Launch
Missing system dependencies for Playwright browsers.
Solution:
Install required dependencies:
sudo apt-get install -y \ libgbm1 \ libgtk-3-0 \ libnss3 \ libasound2 \ libxss1
Windows: Application Won't Start
Missing Visual C++ Redistributables or Windows Defender blocking.
Solutions:
- 1. Install Microsoft Visual C++ Redistributable (latest)
- 2. Add Record Flow to Windows Defender exclusions
- 3. Run as Administrator (right-click → Run as administrator)
Selector Issues
Element Not Found
Most Common Issue
The selector doesn't match any element on the page.
Causes:
- Incorrect selector syntax
- Element hasn't loaded yet
- Element is in an iframe
- Dynamic IDs or classes changed
Solutions:
-
1. Verify selector in DevTools: Open browser DevTools (F12), use
Console to test:
document.querySelector('your-selector') -
2. Add a Wait action: Wait for element to appear before interacting:
Action: Wait Mode: element_visible Selector: your-selector
- 3. Check if element is in iframe: Use Switch to Frame action first
-
4. Use more stable selectors: Prefer IDs or data attributes over
classes:
Good: #submit-btn or [data-testid="submit"] Avoid: .btn.btn-primary.active (too specific)
Multiple Elements Match Selector
The selector matches more than one element.
Solutions:
-
1. Make selector more specific:
Instead of: button Use: #login-form button[type="submit"]
-
2. Use nth-child or nth-of-type:
.product-card:nth-child(2) button
-
3. Use unique attributes:
button[name="login"] button[aria-label="Submit form"]
Element is Visible but Not Clickable
Element exists but click action fails.
Causes:
- Element is covered by another element (modal, overlay)
- Element is disabled
- Element hasn't finished animating
Solutions:
-
1. Scroll element into view first:
Action: Scroll to Element Selector: your-selector
-
2. Add short wait for animations:
Action: Wait Mode: timeout Value: 1000
- 3. Close overlays or modals first
-
4. Check if element is enabled:
Action: Assert Operation: enabled Selector: your-selector
Timing Issues
Action Executes Too Quickly
The next action runs before the page is ready.
Solutions:
-
1. Add Wait for element:
Action: Wait Mode: element_visible Selector: element-that-appears-when-ready
-
2. Wait for navigation:
Action: Wait Mode: navigation
-
3. Wait for network to be idle:
Action: Wait Mode: networkidle
-
4. Add timeout wait:
Action: Wait Mode: timeout Value: 2000
Flow Times Out
Flow fails with timeout errors.
Causes:
- Page takes too long to load
- Element never appears
- Network issues
Solutions:
- 1. Increase timeout in Wait action
- 2. Check network connectivity
- 3. Verify the element actually exists on the page
- 4. Use a faster wait mode (visible instead of attached)
Variable Issues
Variable Not Resolved
Variable shows as literal text instead of value.
Causes:
- Variable doesn't exist in any scope
- Typo in variable name
- Wrong syntax
Solutions:
- 1. Check variable exists in Variables panel
-
2. Verify correct syntax:
Correct: {{username}} Wrong: {username}, $username, %username% - 3. Check variable name matches exactly (case-sensitive)
- 4. Ensure variable is in correct scope (global/workspace/flow)
Runtime Variable Not Available
Variable created by Get Element Text/Attribute is not usable.
Solutions:
- 1. Ensure Get action executed successfully
- 2. Use variable only AFTER it's created (later actions)
- 3. Check variable name has no spaces or special characters
Browser Issues
Browser Doesn't Launch
Selected browser fails to start.
Solutions:
- 1. Try a different browser (Chrome or Edge)
- 2. Restart Record Flow
- 3. Check system has enough resources (RAM, disk space)
- 4. On Linux: Install browser dependencies (see Installation Issues)
Browser Crashes During Execution
Browser closes unexpectedly mid-flow.
Causes:
- Page causes browser crash (memory leak, infinite loop)
- System resources exhausted
- Browser extension conflict
Solutions:
- 1. Try different browser
- 2. Close other applications to free memory
- 3. Test the problematic page manually in browser first
Debugging Tips
General Debugging Strategies
- 1. Run Actions One at a Time: Build flow incrementally, testing each action
- 2. Add Screenshots: Take screenshots before and after problem actions
- 3. Use Browser DevTools: Inspect page, test selectors, check console errors
- 4. Check Action Status: Review which action failed and error message
- 5. Simplify Flow: Remove non-essential actions to isolate the problem
- 6. Test Manually First: Perform the actions manually to verify they're possible
Using Browser DevTools
- 1. Open DevTools: Right-click page → Inspect (or F12)
-
2. Test selectors in Console:
document.querySelector('#your-selector') -
3. Check element properties:
const el = document.querySelector('#elem'); console.log(el.textContent); console.log(el.getAttribute('href')); - 4. View Console for JavaScript errors
- 5. Use Network tab to see if resources are loading
Common Debugging Actions to Add
1. Wait for page load: Action: Wait → Mode: load 2. Wait for element: Action: Wait → Mode: element_visible → Selector 3. Take screenshot: Action: Screenshot → Full Page 4. Verify element exists: Action: Assert → Operation: visible → Selector 5. Add timeout between actions: Action: Wait → Mode: timeout → Value: 1000
Getting Help
If you're still experiencing issues after trying these solutions:
- 1. Check GitHub Issues: Search for similar problems at github.com/Record10/record-flow/issues
- 2. Create New Issue: Provide:
- Record Flow version
- Operating system
- Browser being used
- Steps to reproduce
- Error message or screenshot
- Flow export (if applicable)
- 3. Community Discussions: Ask questions at GitHub Discussions