Troubleshooting

Quick solutions to common Serial Studio issues. If you can't find your problem here, check the Getting More Help section at the bottom.

Table of Contents

Installation Issues

Windows: "Missing VCRUNTIME140.dll" or similar error

Problem: Application won't launch, showing error about missing Visual C++ runtime DLLs.

Solution:

  1. Download and install the Microsoft Visual C++ Redistributable
  2. Get it from: Microsoft's official download page
  3. Install both x64 and x86 versions if unsure
  4. Restart Serial Studio

macOS: "App is damaged and can't be opened" or "Unidentified developer"

Problem: macOS prevents Serial Studio from opening due to security settings.

Solution:

  1. For "damaged" error:

    xattr -cr "/Applications/Serial Studio Pro.app"

    Run this in Terminal, then try opening again. Substitute the exact bundle name shown in /Applications (for example "Serial Studio GPLv3.app" for the GPL build).

  2. For "unidentified developer":

    • Go to System Preferences > Security & Privacy
    • Click "Open Anyway" button next to Serial Studio message
    • Or right-click Serial Studio and select "Open"

Linux: AppImage won't run ("Permission denied")

Problem: Downloaded AppImage file won't execute.

Solution:

  1. Make the AppImage executable:

    chmod +x Serial-Studio-*.AppImage

  2. Run it:

    ./Serial-Studio-*.AppImage

Linux: AppImage error "fuse: failed to exec fusermount"

Problem: AppImage requires FUSE to run.

Solution: Install libfuse2:

Ubuntu/Debian:

sudo apt install libfuse2

Fedora:

sudo dnf install fuse-libs

Arch Linux:

sudo pacman -S fuse2

Linux: Serial port permission denied

Problem: Serial Studio can't access serial ports (permission denied error).

Solution:

  1. Add your user to the dialout group:

    sudo usermod -a -G dialout $USER

  2. Important: Log out and log back in for changes to take effect

  3. Verify you're in the group:

    groups $USER

    You should see dialout in the list

Alternative (temporary, not recommended):

sudo chmod 666 /dev/ttyUSB0  # Replace with your port

Connection Issues

Serial Port

Port not visible in dropdown

Possible causes:

  • Device not connected
  • Driver not installed (Windows)
  • Permission issues (Linux/macOS)
  • Port already in use

Solutions:

  1. Verify device is connected:

    • Check USB cable is plugged in
    • Try a different USB port
    • Check device has power (LED indicators)

  2. Check device is recognized by OS:

    Windows:

    • Open Device Manager (Win+X → Device Manager)
    • Look under "Ports (COM & LPT)"
    • If you see a yellow warning icon, driver is missing

    Linux:

    ls /dev/tty* | grep -E 'ttyUSB|ttyACM'

    macOS:

    ls /dev/tty.*

  3. Install driver if needed (Windows):

  4. Fix permissions (Linux): See Linux serial port permission above

  5. Close other applications using the port:

    • Arduino IDE
    • PuTTY / Screen / Minicom
    • Other Serial Studio instances

"Failed to open port" error

Possible causes:

  • Port already in use by another application
  • Incorrect permissions
  • Device disconnected after selection

Solutions:

  1. Close competing applications:

    • Arduino IDE Serial Monitor
    • PuTTY, Screen, Minicom, Tera Term
    • Other terminal programs

  2. Try reconnecting the device:

    • Unplug USB cable
    • Wait 5 seconds
    • Plug back in
    • Refresh port list in Serial Studio

  3. Check permissions (Linux): See permission fix above

  4. Try different USB port

  5. Restart Serial Studio

Connected but no data appearing

Possible causes:

  • Baud rate mismatch
  • Device not transmitting
  • Wrong COM port selected
  • DTR/RTS signal issues

Solutions:

  1. Verify baud rate matches device:

    • Common rates: 9600, 115200
    • Check your device's code or documentation
    • Try common baud rates: 9600, 19200, 38400, 57600, 115200

  2. Verify device is transmitting:

    • Use Arduino IDE Serial Monitor or another terminal to confirm data output
    • Check device code has Serial.println() or equivalent
    • Verify device is powered and running (LED blink, etc.)

  3. Double-check selected COM port:

    • Disconnect device and see which port disappears
    • Reconnect and select that port

  4. Try toggling the DTR signal:

    • Setup Panel → turn off Send DTR Signal
    • Some devices reset when DTR is asserted

  5. Check frame delimiters:

    • Verify delimiters match what device sends
    • Try "No Delimiters" mode temporarily

Network Socket (TCP/UDP)

Cannot connect to TCP socket

Possible causes:

  • Wrong IP address or port
  • Device not listening
  • Firewall blocking connection
  • Network connectivity issues

Solutions:

  1. Verify IP address and port:

    • Double-check device's IP address (try ping <ip-address>)
    • Verify port number matches device configuration
    • Common mistake: Mixing up TCP and UDP

  2. Verify device is listening:

    • Use telnet to test:
      telnet <ip-address> <port>
    • If "Connection refused", device isn't listening
    • If it hangs, firewall might be blocking

  3. Check firewall:

    • Windows: Windows Defender Firewall → Allow an app
    • macOS: System Preferences → Security & Privacy → Firewall
    • Linux: sudo ufw allow <port>

  4. Verify network connectivity:

    • Make sure computer and device are on same network
    • Try ping <device-ip>

UDP not receiving data

Possible causes:

  • Device sending to wrong IP/port
  • Firewall blocking UDP
  • Network issues

Solutions:

  1. Verify device is sending to correct IP:

    • Check device configuration
    • Computer's IP address might have changed (DHCP)
    • Find your IP:
      • Windows: ipconfig
      • Linux/macOS: ifconfig or ip addr

  2. Check firewall allows UDP:

    • UDP is more likely to be blocked than TCP
    • Allow Serial Studio in firewall

  3. Try listening on all interfaces:

    • Use 0.0.0.0 as listening address (if available)

  4. Use network sniffer to verify packets:

    • Wireshark can show if UDP packets are arriving

Bluetooth LE

BLE device not found during scan

Possible causes:

  • Device not advertising
  • Device already connected to another app
  • Bluetooth disabled
  • Out of range

Solutions:

  1. Verify Bluetooth is enabled:

    • Check OS Bluetooth settings
    • Ensure Bluetooth adapter is present

  2. Ensure device is advertising:

    • Reset/power cycle BLE device
    • Check device isn't already connected (phone app, etc.)
    • Many BLE devices stop advertising once connected

  3. Check range:

    • Move device closer to computer (within 1-2 meters for testing)

  4. Restart Bluetooth:

    • Turn Bluetooth off and on
    • Or restart computer

Connected to BLE but no data

Possible causes:

  • Wrong BLE service/characteristic
  • Device not sending notifications
  • Need to enable notifications

Solutions:

  1. Verify correct service and characteristic:

    • Check device documentation for UUIDs
    • Use BLE scanner app to verify service/characteristic

  2. Ensure notifications are enabled:

    • Serial Studio should automatically enable notifications
    • Try disconnecting and reconnecting

Dashboard & Visualization Issues

Data shows as "0" or "NaN"

Possible causes:

  • Dataset index mismatch
  • Parser function error
  • Data format incorrect

Solutions:

  1. Check dataset indices:

    • Dataset index 1 = array position 0
    • Dataset index 2 = array position 1, etc.
    • Make sure indices match your parser's return array

  2. Check console for JavaScript errors:

    • Look for red error messages
    • Fix any syntax errors in parser function

  3. Add debugging to parser:

    function parse(frame) {
    console.log("Input frame:", frame);
    let result = frame.split(',');
    console.log("Parsed result:", result);
    return result;
}

  4. Verify frame format:

    • Use console output to see raw frames
    • Ensure format matches expectations

Widgets not displaying or showing errors

Possible causes:

  • Wrong widget type for data
  • Missing required datasets
  • Project file corruption

Solutions:

  1. Verify widget requirements:

    • Accelerometer widget needs exactly 3 datasets (X, Y, Z)
    • GPS widget needs latitude and longitude datasets
    • See Widget Reference for requirements

  2. Check widget type matches data:

    • Don't use gauge for text data
    • Don't use bar for unbounded values

  3. Try recreating widget:

    • Delete widget from project
    • Add it again with fresh configuration

Dashboard layout broken after update

Possible causes:

  • Project file format changes between versions
  • Widget API changes

Solutions:

  1. Check release notes for breaking changes

  2. Recreate project file:

    • Export CSV of working session
    • Create new project from scratch
    • Test with CSV Player

  3. Report issue if project file should be compatible

Frame Parsing Issues

Frames not being detected

Problem: Console shows no frames being received, or frames not split correctly.

Debugging steps:

  1. Verify delimiters match exactly:

    • Check delimiters are case-sensitive
    • No extra spaces
    • Use hex view in console to see hidden characters

  2. Check raw console output:

    • Look at actual bytes being received
    • Verify delimiters are present in stream

  3. Try "No Delimiters" mode:

    • Use custom parser to extract frames
    • Useful for binary protocols

  4. Check for line ending issues:

    • Different systems use different line endings:
      • \n (LF) - Linux/macOS
      • \r\n (CRLF) - Windows
      • \r (CR) - Old Mac
    • Try different delimiter combinations

Parser function not working

Problem: JavaScript parser returns errors or wrong data.

Debugging steps:

  1. Check console for errors:

    • Look for "SyntaxError", "TypeError", etc.
    • Fix JavaScript syntax errors

  2. Add logging:

    function parse(frame) {
    console.log("=== PARSER START ===");
    console.log("Type:", typeof frame);
    console.log("Content:", frame);
    console.log("Length:", frame.length);

    // Your parsing logic
    let result = frame.split(',');

    console.log("Result:", result);
    console.log("=== PARSER END ===");
    return result;
}

  3. Verify return value is array:

    // CORRECT
return [1, 2, 3];

// WRONG
return "1,2,3";  // Must be array!

  4. Test with simpler parser first:

    function parse(frame) {
    return frame.split(',');
}

  5. Check decoder method:

    • Plain Text: frame is string
    • Hexadecimal: frame is hex string
    • Base64: frame is base64 string
    • Binary (Direct): frame is byte array

Parse error: "string expected, got table" / "frame.split is not a function"

Problem: The console repeats one of these on every frame:

  • Lua: bad argument #1 to 'byte' (string expected, got table)
  • Lua: attempt to index a table value (local 'frame')
  • JavaScript: TypeError: frame.split is not a function (or frame.match, frame.charCodeAt)

Cause: The source uses the Binary (Direct) decoder, which hands parse() the frame as raw byte values (a 1-indexed table in Lua, an array in JavaScript), but the parser code was written for a string input.

Solutions:

  1. Index the bytes directly instead of using string functions:

    -- Lua: frame[1] is the first byte (1-indexed)
function parse(frame)
  if #frame < 4 then return {} end
  return { (frame[1] << 8) | frame[2], (frame[3] << 8) | frame[4] }
end

    // JavaScript: frame[0] is the first byte (0-indexed)
function parse(frame) {
    if (frame.length < 4) return [];
    return [(frame[0] << 8) | frame[1], (frame[2] << 8) | frame[3]];
}

  2. Need string.unpack (floats, multi-byte fields)? Convert the table to a string once at the top of parse():

    function parse(frame)
  if type(frame) == "table" then
    frame = string.char(table.unpack(frame))
  end
  -- string functions work from here on
end

  3. Or switch the decoder to Plain Text/Hexadecimal in the Project Editor if the device sends text — the decoder and the parser must agree on the frame type. See the decoder table in Frame Parser Scripting.

Dataset transform not working

Problem: You applied a transform(value) function but the dashboard still shows raw values.

Debugging steps:

  1. Check the function is named transform. It has to be exactly function transform(value) (Lua) or function transform(value) { (JavaScript). The name is case-sensitive.

  2. Click Apply in the transform editor. Changes are only saved when you click Apply. Closing the dialog without Apply discards changes.

  3. Test with the built-in Test area. Enter a raw value in the Input field and click Test. If you see an error, fix the function before applying.

  4. Handle non-numeric datasets. The transform receives the raw value as a number when it parses as numeric, otherwise as a string. A non-numeric value like "N/A" is passed to transform() as a string, not skipped, so make sure your function handles the string case.

  5. Check the console for errors. Compilation errors are logged at connect time. Look for [FrameBuilder] Transform compile error messages.

  6. Save and reload the project. If the transform was applied during a live session, saving makes sure it persists. After reload, transforms are recompiled automatically.

See Dataset Value Transforms for the complete reference.

Parsing slow/laggy

Possible causes:

  • Complex parser function
  • Very high data rate
  • Large frames

Solutions:

  1. Optimize parser:

    • Avoid unnecessary operations
    • Use string.split() instead of regex where possible
    • Don't create objects, return simple arrays

  2. Reduce data rate:

    • Slow down device transmission
    • Increase frame interval

  3. Profile parser performance:

    function parse(frame) {
    let start = Date.now();

    // Your parsing logic
    let result = frame.split(',');

    let elapsed = Date.now() - start;
    if (elapsed > 1) {
        console.log("Parse took", elapsed, "ms");
    }
    return result;
}

CSV Player Issues

Cannot open CSV file

Possible causes:

  • File format incorrect
  • File corrupted
  • Wrong encoding

Solutions:

  1. Verify CSV format:

    • First row should be headers
    • Comma-separated values
    • Timestamps in first column

  2. Check file encoding:

    • Should be UTF-8
    • Try opening in text editor to verify

  3. Try export from Serial Studio:

    • Record a short session
    • Export to CSV
    • Compare format with your file

Playback is choppy

Possible causes:

  • Very large file
  • High data rate
  • System performance

Solutions:

The CSV Player replays at the original capture speed; there is no playback-speed control.

  1. Close other applications:

    • Free up system resources

  2. For very large or high-rate files:

    • Split the file into smaller segments
    • Export only the columns you need

Pro Feature Issues

MQTT connection fails

See: MQTT Subscriber and MQTT Publisher. Run Test Connection on the Publisher form to probe broker reachability without disturbing live publishing.

Common issues:

  • Broker address/port incorrect
  • Authentication credentials wrong
  • Firewall blocking connection
  • TLS/SSL certificate issues
  • Client-ID collision between two instances or two sources

Modbus connection fails

See: Protocol-Specific Setup Guides - Modbus

Common issues:

  • Wrong slave ID
  • Incorrect function code
  • Baud rate mismatch (RTU)
  • IP/port wrong (TCP)

CAN Bus issues

See: Protocol-Specific Setup Guides - CAN Bus

Common issues:

  • Bitrate mismatch
  • Missing termination resistors
  • Adapter not recognized
  • DBC file format errors

Pro features show as locked

Problem: Pro features are grayed out or show "Requires Pro License".

Possible causes:

  • Trial expired
  • License key not activated
  • Using GPL build instead of official binary

Solutions:

  1. Check license status:

    • Click Activate in the toolbar to open the License Management dialog
    • It shows whether a Pro license or trial is active

  2. Activate license key:

    • In the License Management dialog, paste your license key and click Activate
    • Internet connection required for activation

  3. Download official binary:

    • If you compiled from source with GPL-only modules, download the official binary from serial-studio.com
    • The official binary includes Pro features (locked behind license)

  4. Check trial status:

    • Trial is 14 days, one trial per version per hardware
    • A new Serial Studio release starts a fresh trial
    • Based on hardware ID (can't reset by reinstalling)

Performance Issues

High CPU usage

Possible causes:

  • High data rate
  • Complex parser function
  • Too many widgets
  • Large plot history

Solutions:

  1. Reduce data rate:

    • Slow down device transmission
    • Increase frame interval on device

  2. Optimize parser:

    • Avoid complex calculations
    • Use efficient string operations

  3. Reduce widgets:

    • Use fewer plots
    • Reduce plot history length

  4. Close unused applications

Memory usage growing over time

Possible causes:

  • Memory leak in parser (global variables)
  • Very long session with plot history
  • Large CSV logging

Solutions:

  1. Check global variables in parser:

    // CAREFUL: This array grows forever
let history = [];
function parse(frame) {
    history.push(frame);  // Memory leak!
    return frame.split(',');
}

// BETTER: Limit size
let history = [];
function parse(frame) {
    history.push(frame);
    if (history.length > 1000) {
        history.shift();  // Remove old entries
    }
    return frame.split(',');
}

  2. Restart Serial Studio periodically for very long sessions

  3. Reduce plot history:

    • Shorter time windows
    • Lower sample rate

Slow frame rate / laggy dashboard

Possible causes:

  • System performance
  • Too many widgets
  • High data rate
  • Many 3D widgets on a slow CPU

Solutions:

  1. Reduce widget count:

    • Serial Studio aims for 60 FPS
    • More widgets = more rendering

  2. Use fewer 3D widgets:

    • 3D Accelerometer, Gyroscope, and 3D Plot are the most CPU-intensive widgets
    • Consider 2D alternatives

  3. Reduce data rate:

    • Dashboard updates at data rate
    • 60 Hz is plenty for visualization

  4. Update graphics drivers

  5. Close background applications

Getting More Help

If you can't find a solution here, try these resources:

1. DeepWiki

AI-powered Q&A for Serial Studio:

2. Search GitHub Issues

Someone may have already solved your problem:

3. GitHub Discussions

Ask the community:

4. Report a Bug

Think you found a bug? Report it:

5. Contact Support

For Pro license holders:

Reporting Bugs Effectively

When reporting an issue, please include:

System Information:

  • Serial Studio version (Help → About)
  • Operating system and version
  • How you installed (official binary, compiled from source, AppImage, etc.)

Problem Description:

  • Clear description of the problem
  • Steps to reproduce (numbered list)
  • Expected behavior
  • Actual behavior

Additional Information:

  • Screenshots or screen recording (if applicable)
  • Console output (copy from console panel)
  • Sample project file (if project-specific)
  • Sample data (a few frames or CSV file)

Example Good Bug Report:

## Problem
Dashboard widgets show "NaN" instead of values

## System
- Serial Studio v3.1.0
- Windows 11 Pro
- Official binary installer

## Steps to Reproduce
1. Connect Arduino Uno via USB (COM3)
2. Configure: Baud 115200, delimiter: \n
3. Load attached project file
4. Open dashboard

## Expected
Gauges should show temperature values (20-30°C)

## Actual
All gauges show "NaN"

## Additional Info
- Console shows: "TypeError: Cannot read property 'split' of undefined"
- Attached: project.json, sample_data.csv
- Screenshot: screenshot.png

See Also

Still stuck? Ask for help on GitHub Discussions. The community is there to help.

Comments

View on GitHub Updated 2026-06-16 · 63 topics
Copied to clipboard!