Scanner FAQ

This document covers common scanner troubleshooting, essential Linux commands, and network configuration for on-site operations. It targets Debian / Ubuntu workstations used with Medipath deployments.

1. Common Scanner Issues

1.1 Scanner Not Detected

Symptoms: The scanner appears offline in scanning software, or the device stays in a perpetual connecting state.

Steps:

Confirm the scanner is powered on and status LEDs are normal (usually solid green or blue).
Check that all data and communication cables between the device and workstation are properly connected.
If using a USB camera, try a different USB cable or port (prefer rear USB 3.0 ports; avoid unpowered USB hubs).
In a terminal, verify whether the system recognizes the network or USB device, and confirm IP address settings on both the system and the device.

bash

# List USB devices
lsusb

# Check whether the kernel detected a new device (run after plugging in the scanner)
dmesg | tail -30

# List block devices (some scanners mount as storage devices)
lsblk

If the vendor device does not appear in lsusb, power-cycle the scanner and host.
Check whether USB autosuspend is putting the device to sleep:

bash

# View current USB power management state
cat /sys/bus/usb/devices/*/power/control

# Temporarily disable USB autosuspend (lost after reboot)
echo 'on' | sudo tee /sys/bus/usb/devices/*/power/control

1.2 USB Permission Denied

Symptoms: A regular user cannot access the scanner; errors such as permission denied or Permission denied appear.

Fix:

bash

# View groups for the current user
groups

# Add the user to dialout and plugdev (log out and back in for this to take effect)
sudo usermod -aG dialout,plugdev $USER

# View udev rules (some vendors provide dedicated rule files)
ls /etc/udev/rules.d/

If the vendor provides a .rules file, copy it to /etc/udev/rules.d/ and run:

bash

sudo udevadm control --reload-rules
sudo udevadm trigger

1.3 Network Scanner Connection Failed

Symptoms: The scanner is connected via Ethernet, but software cannot discover the device or connections time out.

Steps:

Confirm the scanner and workstation are on the same subnet, the Ethernet cable is seated firmly, and switch port LEDs are normal.
Obtain the scanner IP address (usually from the device panel or vendor management software).
Test network connectivity:

bash

# Replace with the scanner's actual IP
ping -c 4 192.168.5.11

# View local IP and default gateway
ip addr show
ip route show

# Scan active hosts on the local subnet (requires arp-scan)
sudo arp-scan --localnet

Check whether the firewall is blocking scanner communication ports:

bash

# View firewall status
sudo ufw status

# Temporarily disable the firewall for testing (re-enable after troubleshooting)
sudo ufw disable

Confirm the scanner IP does not conflict with the workstation IP (investigate if the ARP table shows duplicate MAC addresses).

1.4 Poor Scan Quality

Symptoms: Blurry images, color cast, stripes, black edges, or focus failures.

Common causes and fixes:

Issue	Likely Cause	Action
Blurry image	Dirty objective / uneven slide	Clean the objective; re-seat and flatten the slide
Color cast	Aging light source / white balance not calibrated	Run the vendor white-balance calibration procedure
Horizontal stripes	Loose cable / electromagnetic interference	Replace the cable; move away from strong EMI sources
Black edges / bad crop	Incorrect scan area	Re-select the scan region in scanner software
Focus failure	Slide too thick / air bubbles	Check slide quality; adjust focus parameters

Recommendation: Perform optical calibration per the vendor manual on a regular schedule, and record each calibration date.

1.5 Slow or Stuck Scans

Symptoms: A single slide takes noticeably longer to scan, or the progress bar stalls for a long time.

Steps:

Check remaining disk space (scan caches need adequate free space):

bash

df -h

Check memory and CPU usage:

bash

free -h
top -o %CPU

Check disk I/O on the scan output volume:

bash

# Measure disk write speed (adjust mount point as needed)
sudo apt-get install -y hdparm
sudo hdparm -t /mnt/data

For network scanners, check bandwidth and latency:

bash

# Test network quality to the scanner
ping -c 20 192.168.5.110
iperf3 -c 192.168.5.110   # requires scanner-side support

Close unnecessary background applications, free system resources, and retry the scan.

1.6 Scanner Software Crashes

Symptoms: Double-clicking the scanner application has no effect, or it exits immediately after launch.

Steps:

bash

# Launch from a terminal to capture error output
cd /opt/PathnanoSlideScanner/
./run.sh

# View related errors in system logs
journalctl -xe --no-pager | tail -50

# Check for missing shared libraries
ldd /opt/PathnanoSlideScanner/PathnanoSlideScanner | grep "not found"

# Repair missing dependencies
sudo apt-get update
sudo apt-get install -f -y

If the system kernel or graphics driver was recently updated, try rolling back to a vendor-certified driver version.

1.7 Slide Feed / Eject Failure

Symptoms: Slides jam, fail to load, load repeatedly, or eject abnormally.

Recommended actions:

Stop scanning immediately to avoid mechanical damage from forcing the slide.
Follow the vendor manual for slide cleaning and Home / Reset procedures; wait for the mechanism to return to its home position.
Inspect the slide rack for deformation and check whether the glass slide is broken.
Clean the feed track and remove dust and debris.
If the issue recurs, contact vendor technical support and provide the error code.

1.8 Graphics Card Issues

Symptoms: Scanner software shows corrupted graphics, black screens, or crashes; the preview window has no image; or errors mention OpenGL, CUDA, or graphics drivers.

Common causes and fixes:

Issue	Likely Cause	Action
No signal / black screen	Loose GPU power or video cable; driver not loaded	Check power and video cables; verify driver status after reboot
Graphics driver errors	Driver not installed, version mismatch, or corruption	Reinstall a vendor-certified driver version
Corrupted / torn preview	Bad driver or OpenGL acceleration conflict	Update or roll back the GPU driver; try disabling hardware acceleration
Slow scans / GPU at 100%	Bad driver or poor cooling	Check GPU temperature and fans; clean dust
Cannot reach desktop after kernel update	GPU driver incompatible with new kernel	Boot an older kernel from GRUB; reinstall a matching driver

Steps:

Confirm the system recognizes the GPU:

bash

# View GPU hardware info
lspci | grep -iE 'vga|3d|display'

# NVIDIA GPU: view driver and GPU status (requires driver installed)
nvidia-smi

# View loaded GPU driver modules
lsmod | grep -iE 'nvidia|nouveau|amdgpu|radeon'

If nvidia-smi fails or is missing, check driver installation:

bash

# View recommended drivers (Ubuntu)
ubuntu-drivers devices

# Install recommended driver (example; adjust to the recommended version)
sudo apt-get update
sudo apt-get install -y nvidia-driver-535

# Reboot after installation
sudo reboot

Check kernel logs for GPU-related errors:

bash

dmesg | grep -iE 'nvidia|gpu|drm' | tail -30
journalctl -b | grep -iE 'nvidia|gpu' | tail -30

Verify OpenGL is working (scanner preview often depends on OpenGL):

bash

# Install diagnostic tools
sudo apt-get install -y mesa-utils

# View OpenGL renderer (should show discrete GPU model, not llvmpipe software rendering)
glxinfo | grep -iE 'OpenGL vendor|OpenGL renderer'

If the output shows llvmpipe or Software Rasterizer, the discrete GPU driver is not being used correctly.

When the NVIDIA driver misbehaves, try reloading driver modules:

bash

# View current driver version
cat /proc/driver/nvidia/version

# Reload NVIDIA modules (interrupts the graphical session; use a local console)
sudo systemctl isolate multi-user.target
sudo modprobe -r nvidia_drm nvidia_modeset nvidia_uvm nvidia
sudo modprobe nvidia
sudo systemctl isolate graphical.target

Check GPU temperature and power draw (overheating causes throttling or crashes):

bash

nvidia-smi --query-gpu=temperature.gpu,power.draw,utilization.gpu --format=csv
watch -n 1 nvidia-smi   # real-time monitoring; press Ctrl+C to quit

If a recent system upgrade caused the issue, temporarily boot an older kernel:

Hold Shift (or Esc) during reboot to enter the GRUB menu
Select Advanced options for Ubuntu and boot the previous working kernel
After booting, reinstall a GPU driver that matches the current kernel

Recommendations:

Prefer vendor-certified or field-validated GPU driver versions on scanner workstations; avoid upgrading drivers without testing.
Before installing a driver, confirm the recommended version with ubuntu-drivers devices or vendor documentation.
If scanner software explicitly depends on CUDA, confirm driver compatibility: the maximum supported CUDA version is shown in the top-right corner of nvidia-smi.

2. Essential Linux Commands

The commands below apply to day-to-day Debian / Ubuntu workstation maintenance. Copy and run them directly in an on-site terminal.

2.1 System Info

bash

# View OS version
cat /etc/os-release

# View kernel version
uname -a

# View hostname
hostname

# View uptime and load average
uptime

# View hardware summary
sudo lshw -short

2.2 Users & Permissions

bash

# View current user
whoami

# Switch to root (or use sudo)
sudo -i

# Change file owner
sudo chown user:group /path/to/file

# Change file permissions (example: owner read/write, others read-only)
chmod 644 /path/to/file

2.3 Processes & Services

bash

# List all running processes
ps aux

# Monitor processes in real time (press q to quit)
top
# Or use the more user-friendly htop
sudo apt-get install -y htop && htop

# Find processes by name
pgrep -a scanner

# Terminate a process (try a normal terminate first)
kill <PID>
kill -9 <PID>    # force kill; use only when the process is unresponsive

# View systemd service status
sudo systemctl status caddy
sudo systemctl status docker

# Start / stop / restart a service
sudo systemctl start <service>
sudo systemctl stop <service>
sudo systemctl restart <service>

# Enable a service at boot
sudo systemctl enable <service>

2.4 Disk & Storage

bash

# View disk usage
df -h

# View directory size
du -sh /path/to/dir
du -h --max-depth=1 /home

# View block devices and mount points
lsblk

# Mount an external drive (example)
sudo mkdir -p /mnt/data
sudo mount /dev/sdb1 /mnt/data

# View mount configuration
cat /etc/fstab

2.5 Package Management

bash

# Refresh package index
sudo apt-get update

# Upgrade installed packages
sudo apt-get upgrade -y

# Install a package
sudo apt-get install -y <package>

# Search packages
apt-cache search <keyword>

# List installed packages
dpkg -l | grep <keyword>

# Repair dependency issues
sudo apt-get install -f -y

2.6 Logs

bash

# View recent system logs (last 100 lines)
journalctl -n 100

# Follow logs in real time
journalctl -f

# View logs for a specific service
journalctl -u caddy -n 50
journalctl -u docker -n 50

# View kernel logs
dmesg | less

2.7 File Operations

bash

# List files (including hidden files, with details)
ls -la

# Copy / move / delete
cp -r src/ dest/
mv oldname newname
rm -rf /path/to/dir    # use with caution

# Find files
find /home -name "*.svs"

# View file contents
cat file.txt
less file.txt          # paginated view; press q to quit
tail -f /var/log/syslog  # follow the end of a file in real time

2.8 Docker Commands

When the Medipath backend is deployed with Docker Compose, run these in the deployment directory:

bash

# View container status
docker compose ps

# View container logs
docker compose logs -f expert-service
docker compose logs --tail 100 alg-0

# Restart all services
docker compose restart

# Stop / start
docker compose down
docker compose up -d

3. Network Configuration

3.1 View Current Network Status

bash

# View IP addresses on all interfaces
ip addr show

# Short form
ip a

# View routing table (including default gateway)
ip route show

# View DNS configuration
cat /etc/resolv.conf

# View listening ports
sudo ss -lntp
# Or
sudo netstat -lntp

3.2 Temporary IP Address

Temporary settings are lost after reboot and are suitable for quick on-site testing:

bash

# Set a temporary IP on eth0 (replace with the actual interface name, e.g. enp0s3, ens33)
sudo ip addr add 192.168.1.50/24 dev eth0
sudo ip link set eth0 up
sudo ip route add default via 192.168.1.1

View interface names:

bash

ip link show

3.3 Permanent Static IP (Netplan, Ubuntu 18.04+)

Edit the Netplan config file (filename varies by system):

bash

ls /etc/netplan/
sudo nano /etc/netplan/01-netcfg.yaml

Example configuration:

yaml

network:
  version: 2
  renderer: networkd
  ethernets:
    ens33:
      dhcp4: no
      addresses:
        - 192.168.1.50/24
      routes:
        - to: default
          via: 192.168.1.1
      nameservers:
        addresses:
          - 8.8.8.8
          - 114.114.114.114

Apply the configuration:

bash

sudo netplan apply

3.4 Permanent Static IP (/etc/network/interfaces, Debian)

bash

sudo nano /etc/network/interfaces

Example:

auto eth0
iface eth0 inet static
    address 192.168.1.50
    netmask 255.255.255.0
    gateway 192.168.1.1
    dns-nameservers 8.8.8.8 114.114.114.114

Restart networking:

bash

sudo systemctl restart networking

3.5 DNS Configuration

bash

# Edit DNS (systemd-resolved environment)
sudo nano /etc/systemd/resolved.conf

# Restart after changing DNS
sudo systemctl restart systemd-resolved

# Test DNS resolution
nslookup static.medipath.com.cn
dig static.medipath.com.cn

3.6 Firewall (UFW)

bash

# View status
sudo ufw status verbose

# Allow SSH (allow this before remote maintenance)
sudo ufw allow 22/tcp

# Allow Medipath-related ports (adjust for your deployment)
sudo ufw allow 8090/tcp
sudo ufw allow 8091/tcp
sudo ufw allow 9090/tcp

# Enable firewall
sudo ufw enable

# Disable firewall (temporary use during network troubleshooting)
sudo ufw disable

3.7 Connectivity Tests

bash

# Test loopback
ping -c 4 127.0.0.1

# Test gateway
ping -c 4 192.168.1.1

# Test external network
ping -c 4 8.8.8.8

# Test DNS resolution and HTTPS access
ping -c 4 static.medipath.com.cn
curl -I https://static.medipath.com.cn

# Trace route
traceroute 8.8.8.8

# Test whether a specific port is reachable
nc -zv 192.168.1.100 80
curl -I http://192.168.1.100:80

3.8 Remote Support (RustDesk) Network Settings

After the Palgo deployment script installs RustDesk, fill in Network settings in the client:

Setting	Value
ID Server	`git.medipath.com.cn`
Relay Server	`git.medipath.com.cn`
Key	`Gv4NLEOCdFe3n1b66xQG+yYfVcsZus3qRXCDs2HgcI0=`

If remote connection fails, first confirm the workstation can reach git.medipath.com.cn:

bash

ping -c 4 git.medipath.com.cn
curl -I https://git.medipath.com.cn

4. Quick Checklist

When troubleshooting on site, check in this order:

Step	Check	Command / Action
1	Scanner power and status LEDs	Visual inspection
2	USB / Ethernet cables	Reseat or replace ports or cables
3	Device recognized by the system	`lsusb` / `ping <scanner-ip>`
4	Sufficient disk space	`df -h`
5	Network connectivity	`ip a` / `ping`
6	Services running	`systemctl status` / `docker compose ps`
7	Error logs	`journalctl -xe` / `dmesg`

5. Contact Support

If the steps above do not resolve the issue, contact Medipath technical support and provide:

Scanner brand and model
OS version (cat /etc/os-release output)
Error screenshots or error codes
Relevant logs (journalctl or scanner application logs)

Scanner FAQ ​

1. Common Scanner Issues ​

1.1 Scanner Not Detected ​

1.2 USB Permission Denied ​

1.3 Network Scanner Connection Failed ​

1.4 Poor Scan Quality ​

1.5 Slow or Stuck Scans ​

1.6 Scanner Software Crashes ​

1.7 Slide Feed / Eject Failure ​

1.8 Graphics Card Issues ​

2. Essential Linux Commands ​

2.1 System Info ​

2.2 Users & Permissions ​

2.3 Processes & Services ​

2.4 Disk & Storage ​

2.5 Package Management ​

2.6 Logs ​

2.7 File Operations ​

2.8 Docker Commands ​

3. Network Configuration ​

3.1 View Current Network Status ​

3.2 Temporary IP Address ​

3.3 Permanent Static IP (Netplan, Ubuntu 18.04+) ​

3.4 Permanent Static IP (/etc/network/interfaces, Debian) ​

3.5 DNS Configuration ​

3.6 Firewall (UFW) ​

3.7 Connectivity Tests ​

3.8 Remote Support (RustDesk) Network Settings ​

4. Quick Checklist ​

5. Contact Support ​

Scanner FAQ

1. Common Scanner Issues

1.1 Scanner Not Detected

1.2 USB Permission Denied

1.3 Network Scanner Connection Failed

1.4 Poor Scan Quality

1.5 Slow or Stuck Scans

1.6 Scanner Software Crashes

1.7 Slide Feed / Eject Failure

1.8 Graphics Card Issues

2. Essential Linux Commands

2.1 System Info

2.2 Users & Permissions

2.3 Processes & Services

2.4 Disk & Storage

2.5 Package Management

2.6 Logs

2.7 File Operations

2.8 Docker Commands

3. Network Configuration

3.1 View Current Network Status

3.2 Temporary IP Address

3.3 Permanent Static IP (Netplan, Ubuntu 18.04+)

3.4 Permanent Static IP (/etc/network/interfaces, Debian)

3.5 DNS Configuration

3.6 Firewall (UFW)

3.7 Connectivity Tests

3.8 Remote Support (RustDesk) Network Settings

4. Quick Checklist

5. Contact Support