n8n Workflow Builder

# Release v1.11.1: Explainability Layer Bugfixes 🐛 **Release Date**: 2025-12-16 ## Overview This is a critical bugfix release for v1.11.0 that fixes three major bugs preventing the Explainability Layer tools from working correctly with real n8n workflows. All issues were discovered during testing with production workflows and have been resolved. --- ## 🐛 Bug Fixes ### 1. Schedule Trigger Format Handling **Issue**: `'list' object has no attribute 'get'` error in purpose analysis **Root Cause**: n8n schedule triggers can have their `rule` parameter in two formats: - Dict format: `{"rule": {"interval": [{"expression": "..."}]}}` - List format: `{"rule": [{"expression": "..."}]}` The code only handled dict format. **Fix**: Added defensive handling for both formats in `purpose_analyzer.py`: ```python rule = trigger_params.get("rule", {}) # Handle both dict and list formats if isinstance(rule, dict): interval = rule.get("interval", []) elif isinstance(rule, list): interval = rule else: interval = [] ``` **Affected Tools**: `explain_workflow`, `get_workflow_purpose`, `trace_data_flow` --- ### 2. Timestamp Type Handling **Issue**: `unsupported operand type(s) for -: 'str' and 'str'` error in risk analysis **Root Cause**: n8n execution timestamps can be either: - ISO 8601 strings: `"2025-12-16T15:30:00.000Z"` - Millisecond integers: `1702742400000` The code tried to subtract strings directly. **Fix**: Added timestamp parsing in `risk_analyzer.py`: ```python # Handle both string and int timestamps if isinstance(started, str): from datetime import datetime started_dt = datetime.fromisoformat(started.replace('Z', '+00:00')) stopped_dt = datetime.fromisoformat(stopped.replace('Z', '+00:00')) duration = (stopped_dt - started_dt).total_seconds() else: # Already timestamps in milliseconds duration = (stopped - started) / 1000 ``` **Affected Tools**: `analyze_workflow_risks`, `explain_workflow` --- ### 3. Workflow Response Type Handling **Issue**: `'list' object has no attribute 'get'` when fetching workflow **Root Cause**: n8n API sometimes returns workflows as a list instead of a single dict (edge case with certain API versions or configurations). **Fix**: Added defensive type checking in `server.py`: ```python workflow = await n8n_client.get_workflow(workflow_id) # Handle if API returns list instead of dict if isinstance(workflow, list): workflow = workflow[0] if workflow else {} ``` **Affected Tools**: `explain_workflow`, `trace_data_flow` --- ### 4. Connection Structure Parsing (Critical) **Issue**: `'list' object has no attribute 'get'` in data flow tracing **Root Cause**: n8n workflow connections have a nested list structure: ```json { "NodeName": { "main": [ [ {"node": "TargetNode", "type": "main", "index": 0} ] ] } } ``` This is `List[List[Dict]]`, not `List[Dict]` as initially assumed. The code was trying to call `.get()` on a list: ```python # Before (crashed): for conn in output_connections: target_node = conn.get("node", "") # ❌ conn is a list! ``` **Fix**: Added nested loop to flatten the list structure in `data_flow_tracer.py`: ```python # After (works): for connection_group in output_connections: if isinstance(connection_group, list): for conn in connection_group: # ✅ conn is now a dict! target_node = conn.get("node", "") ``` Applied to both `_build_data_paths()` and `_build_data_lineage()` methods. **Affected Tools**: `explain_workflow`, `trace_data_flow` (both completely broken without this fix) --- ## 🔍 Debugging Improvements ### Enhanced Error Logging Added detailed traceback logging to help diagnose issues: ```python except Exception as e: import traceback logger.error(f"Error in tool {name}: {e}") logger.error(f"Traceback: {traceback.format_exc()}") return [TextContent(type="text", text=f"Error: {str(e)}\n\nTraceback:\n{traceback.format_exc()}")] ``` This dramatically improved debugging speed and helped identify the exact line causing issues. --- ## ✅ Verification All 5 explainability tools have been tested and verified working: 1. ✅ **get_workflow_purpose** - Works with all trigger types 2. ✅ **map_dependencies** - Correctly identifies dependencies 3. ✅ **analyze_workflow_risks** - Handles all timestamp formats 4. ✅ **explain_workflow** - Full workflow documentation generation working 5. ✅ **trace_data_flow** - Data lineage tracing working **Test Workflows**: - FYTA Workflow (schedule trigger with list format) - Backup n8n (12 nodes, complex connections) - Error Test Workflow - Multiple production workflows --- ## 📊 Impact Analysis ### Before v1.11.1: - `explain_workflow`: ❌ Crashed on all workflows - `trace_data_flow`: ❌ Crashed on all workflows - `analyze_workflow_risks`: ❌ Crashed on workflows with string timestamps - `get_workflow_purpose`: ✅ Worked (mostly) - `map_dependencies`: ✅ Worked ### After v1.11.1: - `explain_workflow`: ✅ **FULLY WORKING** - `trace_data_flow`: ✅ **FULLY WORKING** - `analyze_workflow_risks`: ✅ **FULLY WORKING** - `get_workflow_purpose`: ✅ Working (improved) - `map_dependencies`: ✅ Working **Success Rate**: 20% → 100% 🎉 --- ## 🙏 Credits Special thanks to the user who: - Tested all tools thoroughly - Provided detailed error reports - Analyzed the stacktrace to pinpoint the exact issue - Identified the n8n connection structure format This collaborative debugging made the fixes possible in record time. --- ## 📝 Migration Notes ### For Users Upgrading from v1.11.0 **No Breaking Changes**: This is a pure bugfix release. **Immediate Benefits**: - All explainability tools now work correctly - No configuration changes needed - Existing workflows analyzed correctly **Recommended Actions**: 1. Restart your MCP server to load the fixes 2. Re-test any workflows that previously failed 3. Generate documentation for production workflows --- ## 🔜 What's Next With the explainability layer now fully functional, upcoming features: **v1.12.0 (Planned)**: - Visual diagrams (Mermaid.js data flow diagrams) - Workflow comparison mode - Historical explanation tracking - Custom explanation templates --- ## 📚 Documentation For complete documentation on the explainability layer, see: - [v1.11.0 Release Notes](v1.11.0.md) - Original feature documentation - [README.md](../README.md) - Quick start and examples --- ## 🎉 Summary v1.11.1 fixes all critical bugs in the explainability layer: ✅ Schedule trigger format handling ✅ Timestamp type parsing ✅ Workflow response type checking ✅ Connection structure parsing (critical fix) ✅ Enhanced error logging **The explainability layer is now production-ready!** 🚀 All 5 tools (`explain_workflow`, `trace_data_flow`, `map_dependencies`, `analyze_workflow_risks`, `get_workflow_purpose`) are fully functional and tested. --- **Full Changelog**: https://github.com/schimmmi/n8n-workflow-builder/compare/v1.11.0...v1.11.1