Troubleshooting

Solutions for common issues.

Windows Issues

Issue	Solution
"Java is not installed"	Download Java from Adoptium (adoptium.net) or Oracle. Make sure java is in your PATH.
"Build failed"	Delete the target/ folder and retry. Run START_WINDOWS.bat again.
"Device not found"	Try a different USB port. Make sure the Tux Droid dongle is plugged in firmly.
No audio from Tux	Check Windows Sound Mixer for "TuxDroid-Audio" device. Make sure it is not muted.
Antivirus blocks JAR	Add an exception for the ScayTux folder in your antivirus settings.

Issue	Solution
"Permission denied" for USB	Run the launcher script (START_LINUX.sh) which auto-configures udev rules. Or set them up manually.
"espeak not found"	Install with: sudo apt install espeak
"libhidapi not found"	Install with: sudo apt install libhidapi-hidraw0 libhidapi-dev
Need to logout after setup	Group membership (plugdev) requires a re-login or reboot to take effect.
No audio on Linux	Check that PulseAudio or PipeWire is running. Try: aplay -l to list devices.

Issue	Solution
Tux not responding	1. Unplug the dongle. 2. Wait 5 seconds. 3. Plug it back in. 4. Try again.
Spin stutters or is weak	Increase the --val value to 100 or more for a longer spin duration.
TTS sounds robotic	Expected on Linux (espeak). Windows uses native speech synthesis which sounds more natural.
Music plays but no dance	Make sure you are using --play (which auto-dances) or music combos (51-55).
Telegram bot not connecting	Check your internet connection, verify the bot token is correct, and ensure no firewall blocks outbound HTTPS.

If your issue is not listed here: