Troubleshooting

Use this guide to resolve common TrueFidelity Desktop issues. If problems persist, gather diagnostic information and contact support.

Before You Begin

1. Confirm you're running the latest version. Check Help → About if available.
2. Reproduce the issue and note the exact steps, timestamps, and files involved.
3. Gather browser console logs (F12) for debugging if needed.

Installation & Launch

Application Won't Start

Problem: TrueFidelity Desktop fails to launch or crashes immediately.

Solutions:

• Verify Docker Desktop is installed and running before launching the application
• Check that your system meets minimum requirements (8 GB RAM, 50 GB disk space)
• Clear application cache in your user profile directory
• Ensure ports 3000-3010 are not in use by other applications
• Try launching from terminal/command prompt to see error messages

Black Screen or Blank Window

Problem: Application window opens but displays nothing.

Solutions:

• Refresh the application window (Ctrl+R on Windows/Linux, Cmd+R on macOS)
• Update graphics drivers to the latest version
• Clear Electron cache and restart the application
• Check browser console (F12) for JavaScript errors
• Ensure adequate system memory is available

Mode Switching Fails

Problem: Cannot switch between System Design, Monitoring, and CAN Log Analysis modes.

Solutions:

• Save any unsaved work before switching modes
• Allow mode transitions to complete fully (don't click repeatedly)
• Switch layouts using View → Layouts menu
• Stop any active playback or monitoring sessions before switching
• Restart the application if mode switching remains unresponsive

System Design & ECU Management

ECU Won't Start

Problem: ECUs fail to launch when clicking "Start System" in the toolbar.

Solutions:

1. Verify Docker Desktop is running:
2. Check Docker Desktop status in system tray/menu bar
3. Open Docker Desktop and ensure it's fully started

4. Run docker ps in terminal to verify Docker accessibility

5. Check Docker resources:

6. Open Docker Desktop Settings
7. Increase memory allocation to at least 8 GB
8. Allocate at least 4 CPU cores

9. Ensure adequate disk space for containers

10. Review error messages:

11. Check ECU Console panel for startup errors
12. Filter by specific ECU using the dropdown
13. Look for port conflicts or resource limitations

System Canvas Won't Save

Problem: Cannot save system design to JSON file.

Solutions:

• Check write permissions on the save location
• Ensure no other application has the file open
• Verify sufficient disk space available
• Try saving to a different location
• Check that all network connections are valid (ECUs connected to bus nodes)
• Ensure system has at least one ECU and one network

Network Connections Not Working

Problem: Cannot connect ECUs to networks in System Canvas.

Solutions:

• Remember: ECUs connect to bus nodes, not directly to each other
• Drag from ECU port to a bus node on the network (not to the network itself)
• Ensure the network has appropriate bus nodes:
• CAN networks need CAN bus nodes
• Ethernet networks need switch ports
• LIN networks need LIN bus nodes
• Check that ports are properly configured in ECU properties
• Verify network type matches ECU port type

Elements Disappear from Canvas

Problem: ECUs or networks vanish from System Canvas.

Solutions:

• Check zoom level (reset to 100% or use Fit to Screen)
• Pan around canvas to locate elements that may be off-screen
• Verify delete confirmations are enabled in Settings
• Save work frequently to prevent loss
• Reload the system JSON file if elements are missing

ECU Monitoring

ECU Status Shows "Error" or "Unknown"

Problem: ECUs show incorrect status in ECU Hardware Status panel.

Solutions:

1. Check ECU Console panel:
2. Filter by the problematic ECU using dropdown
3. Look for error messages indicating the cause

4. Common issues: missing binaries, port conflicts, resource limits

5. Verify Docker containers: bash docker ps -a # List all containers docker logs <container-id> # View specific container logs

6. Check system configuration:

7. Ensure ECUs are properly connected to bus nodes
8. Verify network configurations match ECU requirements

9. Validate the system JSON file structure

10. Restart ECU containers:

11. Stop the system using toolbar button
12. Clear stopped containers: docker container prune
13. Start system again

Terminal Connection Fails

Problem: Cannot connect to ECU terminal.

Solutions:

• Important: Terminal access is only available for Linux-based ECUs (FSL Linux, Ubuntu)
• ECUs running Zephyr or FreeRTOS do not support terminal access
• For RTOS ECUs, use ECU Console for log viewing instead
• For Zephyr ECUs, enable GDB debugging in ECU properties for detailed analysis
• Verify ECU is running (green status in ECU Hardware Status panel)
• Try reconnecting using the reconnect button in Terminal panel

Network Traffic Empty

Problem: Network Traffic panel shows no CAN messages.

Solutions:

• Ensure ECUs are running and properly connected to networks
• Check that ECU firmware/software is actually sending CAN messages
• Verify Network Traffic panel filters aren't hiding messages
• Clear any CAN ID filters that might be too restrictive
• Ensure the correct network/channel is selected
• Check Console logs for network interface initialization errors

Resource Monitor Shows No Data

Problem: Resource Monitor displays zero or no metrics.

Solutions:

• Verify agent code is included: Resource monitoring data is collected by agent code that runs on the ECU. If the agent code is not included in your firmware build, no data will be available
• Ensure ECUs are actually running (not just defined)
• Adjust time range dropdown to include recent activity
• Verify Resource Monitor panel is visible and not minimized
• Restart ECUs to reset metrics collection
• Check that Docker stats are accessible

Task Monitor Shows No Processes

Problem: Task Monitor panel is empty.

Solutions:

• Ensure correct ECU is selected from dropdown
• Verify ECU has a running operating system
• Some minimal ECU images may not support process monitoring
• Check that monitoring services are enabled for the ECU

Playback & Timeline

Playback Stutters or Freezes

Problem: Signal Player playback is choppy or unresponsive.

Solutions:

1. Optimize performance:
2. Reduce playback speed (start with 1x for large files)
3. Limit visible panels during playback

4. Clear Network Traffic panel if it has accumulated data

5. Improve file handling:

6. Move BLF/MDF4 files to local SSD (avoid network drives)
7. Work with smaller file segments if possible

8. Ensure adequate system memory is available

9. Reduce data complexity:

10. Deselect unnecessary signals in Signal Viewer
11. Limit charted signals to 4-6 maximum
12. Apply filters to reduce displayed messages

Timeline Jumps or Doesn't Progress

Problem: Playback timeline behaves erratically.

Solutions:

• Ensure BLF/MDF4 file is fully loaded before starting playback
• Check that file isn't corrupted (try opening in another CAN tool)
• Clear filters that might be causing timeline issues
• Restart playback from the beginning
• Try different playback speeds

BLF/MDF4 File Won't Open

Problem: Cannot import or load log files.

Solutions:

• Verify file format is BLF or MDF version 4.x
• Check file isn't corrupted or incomplete
• Ensure file size is manageable (files over 2 GB may cause issues)
• Copy file to local storage if on network drive
• Check file permissions and accessibility
• Try opening a smaller test file to verify functionality

Charts & Signals

Charts Blank or Not Updating

Problem: Signal Chart panel shows no data or frozen values.

Solutions:

1. Check signal selection:
2. Ensure signals are selected (checked) in Signal Viewer
3. Verify signals are enabled for charting

4. Limit to 4-6 signals for optimal performance

5. Adjust chart settings:

6. Set appropriate time window (10-60 seconds recommended)
7. Enable auto-scale if signals have different ranges

8. Clear existing chart data and restart

9. Verify data flow:

10. Ensure playback is actually running
11. Check that selected signals exist in the log file
12. Confirm DBC file is loaded if using signal definitions

Signal Not Decoding

Problem: Signals show raw values instead of decoded values.

Solutions:

• Verify the correct DBC file is loaded
• Ensure DBC file matches the CAN network being analyzed
• Check that message IDs in DBC match those in the log
• Verify standard vs. extended CAN ID format matches
• Look for conflicting signal definitions
• Try removing and re-importing the DBC file

Signal Values Incorrect

Problem: Decoded signal values don't match expected values.

Solutions:

• Verify DBC file has correct signal definitions
• Check byte order (Intel vs. Motorola) in signal definition
• Ensure scaling factors and offsets are correct
• Verify signal start bit and length are accurate
• Check that the correct DBC is applied to the right channel

Data Injection

Injection Not Working

Problem: Signal injection from Signal Player doesn't send messages.

Solutions:

1. Check system state:
2. Ensure system is running (ECUs started)
3. Verify injection is enabled in Signal Player

4. Check that target network is active

5. Review configuration:

6. Verify CAN ID and data format
7. Check injection rate isn't too high

8. Ensure network can accept injected messages

9. Monitor feedback:

10. Watch Network Traffic panel for injected messages
11. Check Console logs for injection errors
12. Verify bus isn't in error state

Exports & Reports

Export Takes Too Long or Fails

Problem: CSV or BLF export doesn't complete.

Solutions:

1. Reduce export scope:
2. Export smaller time ranges
3. Select fewer signals

4. Split large exports into segments

5. Check system resources:

6. Verify adequate disk space for export file
7. Ensure export location has write permissions

8. Close other applications to free memory

9. Try alternative formats:

10. BLF export is typically faster than CSV
11. Export raw data if signal decoding slows process

Export File Empty or Incomplete

Problem: Exported file doesn't contain expected data.

Solutions:

• Verify timeline range includes desired data
• Check that signals are selected before export
• Ensure filters aren't excluding data from export
• Confirm source file has data in the selected range
• Try exporting a smaller test range first

UI & Display

Panels Missing or Won't Dock

Problem: UI panels disappear or docking doesn't work correctly.

Solutions:

1. Reset layout:
2. Use View → Layouts to switch to a predefined layout
3. This restores default panel arrangement

4. Save working layouts when stable

5. Fix docking issues:

6. Undock all panels and re-dock one at a time
7. Ensure window is large enough for all panels

8. Check display scaling settings

9. Recover missing panels:

10. Check View menu for panel visibility options
11. Look for panels minimized to edges
12. Restart application if panels remain missing

Dark Theme Display Issues

Problem: Text not readable or UI elements not visible.

Solutions:

• Currently only dark theme is available (light theme planned)
• Adjust monitor brightness and contrast
• Check display color profile settings
• Ensure browser zoom is at 100%
• Update graphics drivers if rendering issues persist

Controls or Buttons Not Responding

Problem: Toolbar buttons or controls don't work.

Solutions:

• Refresh the application (Ctrl/Cmd + R)
• Check browser console (F12) for JavaScript errors
• Ensure the action isn't already in progress
• Verify system state allows the action
• Restart application if controls remain unresponsive

Performance Issues

Application Running Slowly

Problem: UI is sluggish or unresponsive.

Solutions:

1. Optimize Docker resources:
2. Increase Docker Desktop memory/CPU allocation
3. Clean Docker system: docker system prune -a

4. Restart Docker Desktop

5. Reduce UI complexity:

6. Close unnecessary panels
7. Limit number of elements in System Canvas

8. Clear accumulated data in Network Traffic panel

9. Free system resources:

10. Close other applications
11. Check system memory and CPU usage
12. Restart computer if memory leaks suspected

High Memory Usage

Problem: Application consuming excessive RAM.

Solutions:

• Clear Network Traffic panel regularly during long sessions
• Close large files when not actively using them
• Work with smaller BLF file segments
• Reduce number of selected signals
• Restart application to clear memory
• Monitor Docker container memory usage

Docker Issues

Docker Not Accessible

Problem: "Docker daemon not accessible" errors.

Solutions:

1. Verify Docker Desktop status: bash docker ps # Should list containers or show empty list docker version # Should show client and server versions

2. Start Docker Desktop:

3. Windows: Start from Start Menu
4. macOS: Start from Applications

5. Linux: sudo systemctl start docker

6. Check permissions (Linux): bash sudo usermod -aG docker $USER newgrp docker # Or logout and login

Container Resource Issues

Problem: ECU containers fail due to resource limits.

Solutions:

• Increase Docker Desktop resource allocation
• Clean up stopped containers: docker container prune
• Remove unused images: docker image prune -a
• Check disk space for Docker storage
• Monitor with: docker stats

Getting Help

Collecting Diagnostic Information

When reporting issues, gather:

1. System information:
2. TrueFidelity Desktop version (Help → About if available)
3. Operating system and version
4. Docker Desktop version

5. Available RAM and disk space

6. Error details:

7. Screenshots of error messages
8. Browser console logs (F12)
9. Steps to reproduce the issue

10. Sample files if applicable (or file characteristics)

11. Docker status: bash docker version docker ps -a docker stats --no-stream

Browser Console Access

To check for JavaScript errors:

1. Open developer tools:
2. Windows/Linux: F12 or Ctrl+Shift+I

3. macOS: Cmd+Option+I

4. Check Console tab for:

5. Red error messages
6. Yellow warnings

7. Failed network requests

8. Capture errors:

9. Clear console
10. Reproduce the issue
11. Copy error messages

Quick Fixes to Try First

Before detailed troubleshooting:

1. The restart sequence:
2. Save your work
3. Restart TrueFidelity Desktop
4. Restart Docker Desktop if needed

5. Reboot computer as last resort

6. The cleanup routine:

7. Clear browser/application cache
8. Clean Docker environment
9. Remove temporary files

10. Free disk space

11. The verification checklist:

12. Docker Desktop is running
13. Adequate resources available
14. Files are on local storage
15. No conflicting applications

Common Issues Quick Reference

Symptom	Quick Fix
App won't start	Verify Docker is running, check port availability
ECU won't start	Check Docker resources, review ECU Console logs
No CAN traffic	Verify ECUs running, check network connections
Playback stutters	Reduce speed, move file to SSD, close panels
Signals not decoded	Load correct DBC, verify CAN IDs match
Export fails	Reduce time range, check disk space
UI panels missing	View → Layouts to reset, restart application
High memory usage	Clear Network Traffic panel, restart app
Docker errors	Restart Docker Desktop, check resources
Terminal not available	Terminal only for Linux ECUs; use Console for Zephyr

Related Documentation

• Performance Tips - Optimize system performance
• Settings Reference - Configure application settings
• File Compatibility - Supported file formats and limitations