Skip to main content

Troubleshooting

This page covers hardware, the operating system, and installers. Dashboard and recording issues are in Usage troubleshooting.

Restart the Services​

The application runs as systemd services. After a hang, a failed upgrade, or a telemetry change, restart from a root shell:

sudo systemctl status vidredi-server
sudo systemctl restart vidredi-server

sudo systemctl status vidredi-scheduler
sudo systemctl restart vidredi-scheduler

sudo systemctl status nginx
sudo systemctl restart nginx

vidredi-server is the web interface and recording process. vidredi-scheduler runs background maintenance. Nginx terminates HTTPS and proxies the application.

If the web interface is unreachable after a restart, check sudo journalctl -u vidredi-server -e and the application log below.

One of the most common hardware issues is when the system cannot detect your Blackmagic DeckLink card.

Symptoms​

  • Channel fails to start with hardware error
  • No DeckLink inputs available in configuration
  • Error messages mentioning DeckLink device not found

Solutions​

1. Verify Physical Installation​

  • Power down the system completely
  • Check the card is properly seated in the PCIe slot
  • Verify power connections if the card requires additional power
  • Restart the system

2. Check Driver Installation​

# Check if the card is visible to the system
lspci | grep Blackmagic

# Expected output: You should see your DeckLink card listed

If the card is visible but drivers aren't working:

  1. Verify Desktop Video is installed:

    dpkg -l | grep desktopvideo

  2. Reinstall Blackmagic Desktop Video if necessary:

    • Download the latest version from Blackmagic Design
    • Uninstall the old version: sudo dpkg -r desktopvideo
    • Install the new version: sudo dpkg -i <desktop-video-package>.deb

  3. Check Firmware:

    • Use BlackmagicFirmwareUpdater to check if the card firmware is up to date
    • Update firmware if an update is available
    • Restart the system after updating firmware
    BlackmagicFirmwareUpdater status

    Update hardware with:

    BlackmagicFirmwareUpdater update 1
    BlackmagicFirmwareUpdater update 2
    BlackmagicFirmwareUpdater update 3
    BlackmagicFirmwareUpdater update 4

The DeckLink card will not work if it is not updated to the driver version installed. See Command-Line Tools.

3. Check Card Permissions​

Ensure the user running VidRedi has permissions to access the DeckLink device:

# Check device permissions
ls -l /dev/blackmagic/*

# Add user to video group if needed
sudo usermod -a -G video vidredi

# Restart the VidRedi service so group changes take effect
sudo systemctl restart vidredi-server

4. Check for Conflicts​

  • Ensure no other applications are using the DeckLink card
  • Close Media Express or other Blackmagic software
  • Restart VidRedi

General Installation Failures​

If install or upgrade fails, the script names the failed step, the log file, and the command to continue.

  • Check the installation log: /var/log/vidredi/installer.log
  • Re-run the same command. Steps are idempotent and will skip work that is already done.
  • To resume at the failed step: sudo /opt/vidredi/current/scripts/install.sh --from <step-id>
  • A previous software tree is kept at /opt/vidredi/current.backup (and current.backup.prev for the one before that). Data is not copied during upgrades.
  • If current is missing after a failed swap, re-run the installer. It treats current.backup as an interrupted upgrade, not a blank machine.

See Updates and Upgrades for the full upgrade paths.

Network Problems and Debugging​

Network-related issues affect streaming and download channels. Operators should confirm the stream address first; see Usage troubleshooting.

Stream Connection Failures​

  1. Verify Network Connectivity:

    # Ping the stream server
    ping <server-address>

    # Check route to server
    traceroute <server-address>

  2. Check Firewall Rules:

    # Check if ports are blocked
    sudo iptables -L -n | grep <port>

    # Allow required ports if needed
    sudo ufw allow <port>/tcp

Bandwidth Issues​

  1. Monitor Network Usage:

    # Install iftop if not available
    sudo apt-get install iftop

    # Monitor bandwidth usage
    sudo iftop -i <interface>

  2. Network Optimization:

    • Use a wired connection instead of WiFi
    • Ensure network equipment (switches, routers) can handle bandwidth
    • Check for network congestion

Logs and Where They're Located​

Logs are essential for troubleshooting detailed issues.

On-disk locations​

LogPath
Application/var/log/vidredi/system.log
Installer / upgrade/var/log/vidredi/installer.log
System/var/log/syslog
Package/var/lib/vidredi/packages/<package-id>/logs/

Each package log folder corresponds to work done for that recording. Files under it contain everything that was logged for that package.

If install or upgrade fails, re-run the same scripts/install.sh command (add --from <step> to resume at the failed step). See General Installation Failures.

Viewing Logs​

# Application log
sudo tail -f /var/log/vidredi/system.log

# Installer / upgrade log
sudo tail -f /var/log/vidredi/installer.log

# System log
sudo tail -f /var/log/syslog

# Package-specific logs
sudo tail -f /var/lib/vidredi/packages/<package-id>/logs/*.log

# Search for errors
sudo grep -i error /var/log/vidredi/system.log

Log verbosity is set on Configuration → System (Error, Warn, Info, Debug, Verbose, Silly). Leave production systems on Info unless you are diagnosing a problem. The in-browser viewer is on Configuration → Logs. See Configuration.

Debugging overlay (D key)​

Press D on a selected channel for pipeline state, buffer fill, and (on stream channels) network stats.

Storage Write Failures​

If recordings cannot be written:

  • Check disk space: df -h
  • Verify write permissions on /var/lib/vidredi
  • Check for disk errors: dmesg | grep -i error

The data path is documented in Storage and Environment.

Performance Issues​

High CPU Usage​

Causes:

  • Too many channels running
  • Inefficient encoding settings

Solutions:

  • Reduce number of simultaneous channels
  • Use hardware encoding if available
  • Lower Bitrate (Kbps) on encode templates
  • Upgrade CPU

Dropped Frames​

Causes:

  • Insufficient system resources
  • Disk I/O bottleneck
  • Network issues (streaming channels)

Solutions:

  • Monitor system resources: top or htop
  • Use faster storage (SSD/NVMe)
  • Reduce recording quality/bitrate
  • Fix network issues

Getting Additional Help​

If you cannot resolve an issue:

  1. Collect Information:

    • Exact error messages
    • Relevant log entries
    • System configuration
    • Steps to reproduce the issue

  2. Check Logs:

    • Application logs
    • System logs

  3. Contact Support:

    • See Support
    • Include collected information
    • Provide log excerpts (not entire log files)