doc/help/Troubleshooting.md
Quick solutions to common Serial Studio issues. If you can't find your problem here, check the Getting More Help section at the bottom.
Problem: Application won't launch, showing error about missing Visual C++ runtime DLLs.
Solution:
Problem: macOS prevents Serial Studio from opening due to security settings.
Solution:
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).
For "unidentified developer":
Problem: Downloaded AppImage file won't execute.
Solution:
Make the AppImage executable:
chmod +x Serial-Studio-*.AppImage
Run it:
./Serial-Studio-*.AppImage
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
Problem: Serial Studio can't access serial ports (permission denied error).
Solution:
Add your user to the dialout group:
sudo usermod -a -G dialout $USER
Important: Log out and log back in for changes to take effect
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
Possible causes:
Solutions:
Verify device is connected:
Check device is recognized by OS:
Windows:
Linux:
ls /dev/tty* | grep -E 'ttyUSB|ttyACM'
macOS:
ls /dev/tty.*
Install driver if needed (Windows):
Fix permissions (Linux): See Linux serial port permission above
Close other applications using the port:
Possible causes:
Solutions:
Close competing applications:
Try reconnecting the device:
Check permissions (Linux): See permission fix above
Try different USB port
Restart Serial Studio
Possible causes:
Solutions:
Verify baud rate matches device:
Verify device is transmitting:
Serial.println() or equivalentDouble-check selected COM port:
Try toggling the DTR signal:
Check frame delimiters:
Possible causes:
Solutions:
Verify IP address and port:
ping <ip-address>)Verify device is listening:
telnet <ip-address> <port>
Check firewall:
sudo ufw allow <port>Verify network connectivity:
ping <device-ip>Possible causes:
Solutions:
Verify device is sending to correct IP:
ipconfigifconfig or ip addrCheck firewall allows UDP:
Try listening on all interfaces:
Use network sniffer to verify packets:
Possible causes:
Solutions:
Verify Bluetooth is enabled:
Ensure device is advertising:
Check range:
Restart Bluetooth:
Possible causes:
Solutions:
Verify correct service and characteristic:
Ensure notifications are enabled:
Possible causes:
Solutions:
Check dataset indices:
Check console for JavaScript errors:
Add debugging to parser:
function parse(frame) {
console.log("Input frame:", frame);
let result = frame.split(',');
console.log("Parsed result:", result);
return result;
}
Verify frame format:
Possible causes:
Solutions:
Verify widget requirements:
Check widget type matches data:
Try recreating widget:
Possible causes:
Solutions:
Check release notes for breaking changes
Recreate project file:
Report issue if project file should be compatible
Problem: Console shows no frames being received, or frames not split correctly.
Debugging steps:
Verify delimiters match exactly:
Check raw console output:
Try "No Delimiters" mode:
Check for line ending issues:
\n (LF) - Linux/macOS\r\n (CRLF) - Windows\r (CR) - Old MacProblem: JavaScript parser returns errors or wrong data.
Debugging steps:
Check console for errors:
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;
}
Verify return value is array:
// CORRECT
return [1, 2, 3];
// WRONG
return "1,2,3"; // Must be array!
Test with simpler parser first:
function parse(frame) {
return frame.split(',');
}
Check decoder method:
frame is stringframe is hex stringframe is base64 stringframe is byte arrayProblem: The console repeats one of these on every frame:
bad argument #1 to 'byte' (string expected, got table)attempt to index a table value (local 'frame')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:
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]];
}
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
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.
Problem: You applied a transform(value) function but the dashboard still shows raw values.
Debugging steps:
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.
Click Apply in the transform editor. Changes are only saved when you click Apply. Closing the dialog without Apply discards changes.
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.
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.
Check the console for errors. Compilation errors are logged at connect time. Look for [FrameBuilder] Transform compile error messages.
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.
Possible causes:
Solutions:
Optimize parser:
Reduce data rate:
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;
}
Possible causes:
Solutions:
Verify CSV format:
Check file encoding:
Try export from Serial Studio:
Possible causes:
Solutions:
The CSV Player replays at the original capture speed; there is no playback-speed control.
Close other applications:
For very large or high-rate files:
See: MQTT Subscriber and MQTT Publisher. Run Test Connection on the Publisher form to probe broker reachability without disturbing live publishing.
Common issues:
See: Protocol-Specific Setup Guides - Modbus
Common issues:
See: Protocol-Specific Setup Guides - CAN Bus
Common issues:
Problem: Pro features are grayed out or show "Requires Pro License".
Possible causes:
Solutions:
Check license status:
Activate license key:
Download official binary:
Check trial status:
Possible causes:
Solutions:
Reduce data rate:
Optimize parser:
Reduce widgets:
Close unused applications
Possible causes:
Solutions:
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(',');
}
Restart Serial Studio periodically for very long sessions
Reduce plot history:
Possible causes:
Solutions:
Reduce widget count:
Use fewer 3D widgets:
Reduce data rate:
Update graphics drivers
Close background applications
If you can't find a solution here, try these resources:
AI-powered Q&A for Serial Studio:
Someone may have already solved your problem:
Ask the community:
Think you found a bug? Report it:
For Pro license holders:
When reporting an issue, please include:
System Information:
Problem Description:
Additional Information:
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
Still stuck? Ask for help on GitHub Discussions. The community is there to help.