Skip to main content

Troubleshooting

Solutions to common issues with Petal Metrics.

Connection Issues​

Muse headband not appearing in device list​

Symptoms: The device scanner doesn't show your Muse headband.

Solutions:

  1. Check Muse is powered on - Press and hold the power button until you hear a tone
  2. Enable pairing mode - The LED should be blinking
  3. Check Bluetooth - Ensure Bluetooth is enabled on your computer
  4. Move closer - Stay within 3 meters of your computer
  5. Restart Bluetooth - Toggle Bluetooth off and on
  6. Restart Muse - Power off the headband and power it back on
  7. Restart the app - Close and reopen Petal Metrics

Platform-specific:

  • Windows: Update Bluetooth drivers from Device Manager
  • macOS: Reset Bluetooth module (Shift+Option+Click Bluetooth menu → Debug → Reset)
  • Linux: Ensure bluez is installed and running

Connection drops frequently​

Symptoms: Connection established but drops after a few seconds or minutes.

Solutions:

  1. Reduce distance - Stay closer to your computer
  2. Remove interference - Move away from Wi-Fi routers, USB 3.0 hubs, microwaves
  3. Check battery - Low Muse battery can cause disconnections
  4. Disable other Bluetooth - Temporarily disconnect other Bluetooth devices
  5. Update drivers (Windows) - Get latest Bluetooth drivers

"Bluetooth not available" error​

Symptoms: App reports no Bluetooth adapter found.

Solutions:

  1. Verify hardware - Confirm your computer has Bluetooth 4.0+ (BLE)
  2. Check system settings - Bluetooth should be enabled
  3. Install drivers - Install/update Bluetooth drivers
  4. Linux: Install required packages: 
    sudo apt-get install bluez bluetooth

Signal Quality Issues​

Red/poor signal on all electrodes​

Symptoms: All electrodes show poor contact.

Solutions:

  1. Clean sensors - Wipe with a slightly damp cloth
  2. Moisten skin - Apply a small amount of water to sensor contact points
  3. Adjust fit - Reposition headband for firm contact
  4. Remove hair - Ensure sensors contact skin directly
  5. Check battery - Low battery can affect signal quality

Intermittent signal quality​

Symptoms: Signal quality fluctuates between good and poor.

Solutions:

  1. Stay still - Movement causes signal artifacts
  2. Tighten fit - Headband may be too loose
  3. Check for sweat - Excessive moisture can affect readings
  4. Environmental interference - Move away from electronic devices

Login and Authentication Issues​

Can't sign in with email/password​

Solutions:

  1. Reset password - Use "Forgot password?" on the login screen
  2. Check email - Ensure you're using the correct email address
  3. Check internet - Login requires network connection

GitHub login not working​

Solutions:

  1. Complete authorization - Copy the code shown and enter it at github.com/login/device
  2. Check GitHub account - Ensure your GitHub account has a verified email
  3. Try again - Click "Continue with GitHub" to get a fresh code
  4. Use email login - As an alternative, sign in with email/password

License and Subscription Issues​

"License validation failed"​

Symptoms: App shows license validation error on startup.

Solutions:

  1. Check internet - Validation requires network connection
  2. Verify subscription - Confirm at petal.tech/account
  3. Sign out and in - Settings → Account → Sign Out, then sign back in
  4. Check system time - Incorrect date/time can cause validation failures

"Maximum devices reached"​

Symptoms: Can't activate license on a new device.

Solutions:

  1. Revoke old device - Go to petal.tech/account/downloads
  2. Click Revoke on a device you no longer use
  3. Try activation again - Sign in on your new device

Subscription shows inactive​

Symptoms: Features are locked despite having a subscription.

Solutions:

  1. Check payment - Your payment may have failed
  2. Update payment method at petal.tech/account/subscription
  3. Contact support if payment shows successful but access is denied

Streaming Issues​

OSC data not being received​

Symptoms: Receiving application shows no data.

Solutions:

  1. Verify OSC is enabled - Settings → Output → Enable OSC
  2. Check host/port - Must match receiving application
  3. Check firewall - Allow UDP traffic on your chosen port
  4. Test locally first - Use 127.0.0.1 before trying network streaming
  5. Verify receiving app - Confirm it's actually listening

LSL stream not found​

Symptoms: LabRecorder or other LSL apps don't see Muse streams.

Solutions:

  1. Verify LSL is enabled - Settings → Output → Enable LSL
  2. Check stream name - Search matches your prefix (e.g., "Muse_EEG")
  3. Wait a moment - LSL discovery can take a few seconds
  4. Check firewall - LSL uses ports 16571-16600
  5. Same network - Both computers must be on same network segment

Webhook requests failing​

Symptoms: Test connection fails or data not arriving.

Solutions:

  1. Verify URL - Must be a valid HTTPS URL
  2. Check server - Ensure your endpoint is running
  3. Test with webhook.site - Use a test endpoint to verify data format
  4. Check authentication - Add required headers in Custom Headers
  5. Review server logs - Check for errors on receiving end

Installation Issues​

Windows: "Windows protected your PC"​

Solution: Click More info → Run anyway

macOS: "App is damaged and can't be opened"​

Solution: Run in Terminal:

xattr -cr /Applications/Petal\ Metrics.app

macOS: "Petal Metrics cannot be opened"​

Solution: Right-click the app → Open → Click "Open" in dialog

Linux: Missing dependencies​

Solution: Install required libraries:

sudo apt-get install libwebkit2gtk-4.0-37 libgtk-3-0 libayatana-appindicator3-1

Linux: App won't start​

Solution: Run from terminal to see error messages:

/opt/petal-metrics/petal-metrics

Performance Issues​

High CPU usage​

Symptoms: Computer fan running, sluggish performance.

Solutions:

  1. Close unused streams - Disable streaming outputs you're not using
  2. Reduce visualization - Pause when not actively viewing
  3. Check other apps - Close resource-intensive applications
  4. Update graphics drivers - Outdated drivers can cause issues

App freezes or crashes​

Solutions:

  1. Update the app - Download latest version from your account
  2. Restart computer - Clear any stuck processes
  3. Check logs - Report crashes to support with log files
  4. Reduce streams - Try with fewer output streams enabled

Still Need Help?​

If you've tried the above solutions and still have issues:

  1. Check the FAQ for additional answers
  2. Gather information:
    • Operating system and version
    • Petal Metrics version
    • Muse model (Muse 2, Muse S)
    • Steps to reproduce the issue
  3. Contact support: support@petal.tech