Skip to content

Troubleshooting

Jump to bottom
W9KSB edited this page Jun 11, 2026 · 5 revisions

Troubleshooting

Service Does Not Start

Check service status:

sudo systemctl status pi-sat
journalctl -u pi-sat -f

Common causes:

  • invalid config file
  • missing Python dependencies
  • missing Hamlib utilities
  • malformed TLE source configuration

If the service is not starting and the config file is suspected, you can easily revert to the original, default, config and backup the current file if you would like with these commands:

cd ~/pi-sat
mv pi-sat-controller.conf pi-sat-controller.conf.bak
cp pi-sat-controller.conf.example pi-sat-controller.conf
sudo systemctl restart pi-sat
sudo systemctl status pi-sat

Settings Page Loads Incorrectly

If the browser is showing stale UI assets, force a hard refresh. If caching has been disabled in config, the backend should serve the frontend with no-cache headers.

No Passes Showing

Check the following:

  • station coordinates are correct
  • tracked satellites are configured
  • TLE data exists and is current
  • the selected satellites are present in the merged TLE cache

If a TLE source fails, Pi-Sat may still run on an older cache, but missing satellites in the cache will not produce passes.

TLE Download Failures

Common causes:

  • remote source unavailable
  • source returns HTTP errors
  • source blocks access
  • malformed source list in config

If one source fails and others succeed, the merge can still complete.

Wrong Time Zone or Pass Time Display

Pi-Sat derives display timezone from the configured station coordinates, not from a hardcoded Eastern time zone assumption or anything like that. If times look wrong, verify the station location first.

SDR or Radio Does Not Track

Check:

  • device is enabled in config
  • correct connectivity mode is selected
  • correct host/port or serial path is configured
  • Hamlib can control the device outside Pi-Sat
  • write control is enabled where required

Local Serial Device Problems

Check:

  • the serial path exists
  • the chosen path is stable
  • the Pi user has permission to access the device
  • the baud rate and model ID are correct

Rotator Does Not Move

Check:

  • rotator control is enabled
  • rotator writes are enabled
  • the pass is actually active
  • target elevation is above the configured minimum elevation
  • local or network rotctld is reachable and functioning

If pass tracking is inactive, Pi-Sat should not be sending tracking commands.

Frequency Does Not Match Other Software

Possible causes:

  • different TLE source quality
  • stale TLE data
  • different Doppler update timing
  • radio readback lag
  • manual user offset still applied

Before changing the tracking logic, compare:

  • Pi-Sat target frequency
  • actual radio readback
  • another tracking program
  • observed signal location on the waterfall

Browser Looks Wrong After Update

Start with:

  • hard refresh
  • service restart

Then verify whether browser asset caching is enabled or disabled in config.

Clone this wiki locally