Pipeline Troubleshooting

Common issues, error messages, and how to fix them.

Quick Fixes

Pipeline Won’t Run

Symptoms:

• Nothing happens when clicking Run
• No error message

Solutions:

1. Check connections — Make sure nodes are connected
2. Check input data — Ensure Input node has valid JSON
3. Check configuration — Open each step and verify required fields are filled
4. Reload page — Sometimes transient issues clear on refresh

Step Shows Red Error Badge

Symptoms:

• Step node shows an error state
• Pipeline stopped at this step
• Downstream steps didn’t run

Solutions:

1. Click the step — See the error message
2. Read the error — Error messages are specific and actionable
3. Fix the issue — See specific errors below
4. Re-run — Click Run again after fixing

No Output in Result Node

Symptoms:

• Pipeline ran successfully
• Output node is empty
• No error message

Solutions:

1. Check last step — Click the final step to see its output
2. Check connections — Make sure last step connects to Output node
3. Verify step logic — Some utilities may produce empty results
4. Check input data — Empty input = empty output

Common Error Messages

”Invalid JSON”

Cause: Input data is not valid JSON

Fix:

1. Open Input node
2. Verify JSON syntax:
   • All strings in double quotes
   • No trailing commas
   • Proper bracket/brace matching
3. Use a JSON validator to find errors
4. Fix and re-run

Example of invalid JSON:

{
  name: "John",  // Missing quotes around key
  'age': 32,    // Single quotes instead of double
  city: "NYC",  // Trailing comma →
}

Valid JSON:

{
  "name": "John",
  "age": 32,
  "city": "NYC"
}

“Path not found: $.users.name”

Cause: JSON path doesn’t exist in your data

Fix:

1. Explore your data structure:
   • Click Input node
   • Use Tree View to expand objects
   • Find the correct path to the field
2. Use the correct path:
   • $.users.0.name for first item in array
   • $.users.name for field in all items
3. Check for typos in field names
4. Re-run with correct path

Common mistakes:

• Using user instead of users
• Using name when nested under user.name
• Forgetting array indices: users[0].name

”Missing required configuration”

Cause: Step is missing required settings

Fix:

1. Click the step with the error
2. Look for highlighted fields in configuration panel
3. Fill in all required fields (marked with *)
4. Save (if manual save required)
5. Re-run the pipeline

Example:

• Filter Fields requires fields to keep
• Rename Keys requires mapping or transform
• Find & Replace requires search and replacement

”Utility not found: xyz”

Cause: Utility doesn’t exist or ID is wrong

Fix:

1. Check utility ID in step configuration
2. Browse available utilities in the sidebar
3. Use the correct utility ID:
   • cleanup.clean-json (not cleanjson)
   • structure.pick-fields (not pickfields)
4. Replace the step with correct utility

”Execution timeout”

Cause: Pipeline took too long to execute

Fix:

1. Check dataset size — Large datasets take longer
2. Simplify pipeline — Remove unnecessary steps
3. Optimize steps:
   • Filter early (reduce data size)
   • Pick fields first (fewer fields = faster)
   • Avoid expensive operations on large arrays
4. Try again — Sometimes transient slowdowns occur

”Out of memory”

Cause: Dataset too large for available memory

Fix:

1. Reduce dataset size — Filter or sample data
2. Simplify pipeline — Fewer steps = less memory
3. Close other tabs — Free up browser memory
4. Use smaller dataset — Process in chunks if possible

Performance Issues

Pipeline is Slow

Diagnosis:

1. Check step timings — Review duration labels shown for completed steps when available
2. Find slowest step — Look for steps taking > 5 seconds
3. Identify bottleneck — Usually aggregation or complex transformations

Solutions:

• Filter early — Remove unnecessary data before expensive operations
• Pick fields — Reduce number of fields early
• Avoid redundant steps — Don’t process same data multiple times
• Split pipeline — Break into multiple smaller pipelines

UI Freezes During Execution

Cause: Worker may have crashed or hung

Fix:

1. Check browser console — Look for worker errors
2. Reload page — Terminates and restarts worker
3. Try simpler pipeline — Test with basic steps
4. Report issue — If problem persists

Connection Issues

Nodes Won’t Connect

Symptoms:

• Dragging connection doesn’t create a line
• Connection disappears when released
• “Can’t connect these nodes” message

Causes:

1. Incompatible types — Some connections aren’t allowed
2. Wrong handles — Must drag from output to input
3. Self-connection — Can’t connect node to itself

Fix:

1. Drag from output handle (right side) to input handle (left side)
2. Check compatibility — Not all connections are valid
3. Use intermediate node — Connect A → B → C instead of A → C

Auto-Connect Not Working

Symptoms:

• Dragging utility doesn’t auto-connect
• Have to manually wire everything

Fix:

1. Drag closer to existing node — Auto-connect has a range
2. Check for compatible handles — Must be near input handle
3. Manually connect — Auto-connect is convenience, not required

Data Issues

Results Not What I Expected

Diagnosis:

1. Click each step — See output at each point
2. Find where it went wrong — Look for unexpected transformation
3. Check configuration — Verify settings are correct

Common mistakes:

• Wrong utility — Using Pick Fields when you meant Remove Fields
• Wrong order — Filtering after aggregation
• Case sensitivity — “Name” ≠ “name”
• Wrong data type — Expecting number but got string

Data Changed Unexpectedly

Diagnosis:

1. Check step configuration — Look for unexpected settings
2. Review utility behavior — Read utility description
3. Test with simple data — Verify understanding

Example:

• Clean JSON removes null values — expected behavior
• Rename Keys with uppercase transform — expected behavior
• Filter Fields keeps only specified fields — expected behavior

Browser-Specific Issues

Safari Issues

Known issues:

• OPFS not supported (falls back to IndexedDB)
• Slower storage performance
• Some keyboard shortcuts differ

Workarounds:

• Use Chrome/Edge for better performance
• Or accept slower storage in Safari

Firefox Issues

Known issues:

• OPFS not supported (falls back to IndexedDB)
• Different keyboard shortcuts (Ctrl vs Cmd)
• Some DevTools features missing

Workarounds:

• Use Chrome/Edge for best experience
• Or adapt to Firefox differences

Mobile Browsers

Limitations:

• Smaller screen size
• Touch interface (no hover)
• Limited DevTools
• Slower performance

Tips:

• Use tablet over phone when possible
• Connect external keyboard for shortcuts
• Use desktop for complex pipelines

Getting Help

Self-Service Resources

1. Check this guide — Look for your specific issue
2. Read utility descriptions — Understand what each utility does
3. Review examples — See Use Cases
4. Try simpler pipeline — Isolate the problem

Community Support

1. Search existing issues — Someone may have solved it
2. Ask in community forum — Provide details:
   • Pipeline structure (screenshot or description)
   • Input data (sanitized sample)
   • Expected output
   • Actual output
   • Error messages

Reporting Bugs

When reporting bugs, include:

1. Steps to reproduce — What you did
2. Expected behavior — What should happen
3. Actual behavior — What actually happened
4. Screenshots — Visual evidence
5. Browser info — Browser, version, OS
6. Console errors — Any errors in DevTools console

Prevention

Best Practices

1. Start simple

• Begin with basic pipeline
• Add complexity gradually
• Test at each step

2. Use sample data

• Test with small dataset first
• Verify logic before scaling up
• Catch errors early

3. Save frequently

• Create version checkpoints
• Manual save before big changes
• Easier to rollback if needed

4. Document your pipeline

• Add descriptions to steps
• Name steps meaningfully
• Easier to understand later

5. Test incrementally

• Run after each major change
• Verify output is correct
• Catch problems early

Error Reference

Validation Errors

Execution Errors

System Errors

Next Steps

• Execution Guide — How to run pipelines
• Performance — Optimization tips
• Building Basics — Creating pipelines