Troubleshooting

General Troubleshooting

System Won't Boot

Symptoms:

No power LED
Black screen
Boot hangs

Solutions:

Check Power Supply

# Verify power adapter is 19V
# Check power connector is fully seated
# Try a different power outlet

Check Boot Media

# If using microSD, verify card integrity
sudo fsck /dev/mmcblk0p1

# Check if card is readable
lsblk

Reset to Factory Settings
- Hold recovery button while powering on
- Follow recovery procedure in NVIDIA documentation

System Overheating

Symptoms:

System throttling
Unexpected shutdowns
High temperature readings

Solutions:

# Check current temperature
cat /sys/devices/virtual/thermal/thermal_zone*/temp

# Monitor temperature in real-time
watch -n 1 cat /sys/devices/virtual/thermal/thermal_zone*/temp

# Check if thermal throttling is active
dmesg | grep -i thermal

Prevention:

Ensure proper ventilation
Use active cooling if available
Reduce power mode if not needed:
```
sudo nvpmodel -m 1  # 10W mode
```

Out of Memory Errors

Symptoms:

"Out of memory" errors
System becomes unresponsive
Applications crash

Solutions:

# Check memory usage
free -h

# Check swap usage (Field Kit has 16GB swap pre-configured)
swapon --show

# If swap is not enabled, enable it
sudo swapon /swapfile

# Verify swap is active
free -h
# Should show swap space available

# If swap file doesn't exist, create 16GB swap (Field Kit standard)
sudo fallocate -l 16G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Make swap permanent
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Prevention:

Monitor memory usage in applications
Use model quantization for ML workloads
Close unused applications

Camera Issues

Camera Not Detected

Symptoms:

v4l2-ctl --list-devices shows no camera
Applications can't access camera
Only one camera detected (should be two)

Solutions:

Check Physical Connection

# Verify BOTH ribbon cables are properly seated (CAM0 and CAM1)
# Check cable orientation (contacts must face inward toward Jetson)
# Ensure camera modules are powered
# Field Kit includes dual IMX219 cameras - both should be connected

Check Device Tree

# List camera devices (should show /dev/video0 and /dev/video1)
ls -la /dev/video*

# Check kernel messages
dmesg | grep -i camera
dmesg | grep -i csi
dmesg | grep -i imx219

Configure Cameras in Jetson I/O

# Run Jetson I/O configuration tool
sudo /opt/nvidia/jetson-io/jetson-io.py

# Select: Configure Jetson Expansion Header
# Select: Configure Camera IMX219-A CSI port with camera IMX219
# Configure both CAM0 and CAM1

Reload Camera Modules

sudo modprobe -r tegra_video
sudo modprobe tegra_video

Check Camera Permissions

# Add user to video group
sudo usermod -a -G video $USER
# Log out and back in

Verify Dual Camera Setup

# Should show both cameras
v4l2-ctl --list-devices

# Expected output:
# vi-output, imx219 9-0010 (platform:tegra-capture-vi:2):
#     /dev/video0
# vi-output, imx219 10-0010 (platform:tegra-capture-vi:1):
#     /dev/video1

Poor Image Quality

Symptoms:

Blurry images
Incorrect colors
Low frame rate

Solutions:

# Check camera settings
v4l2-ctl --device=/dev/video0 --all

# Set optimal resolution and format
v4l2-ctl --device=/dev/video0 \
  --set-fmt-video=width=1920,height=1080,pixelformat=YUYV

# Adjust exposure and gain
v4l2-ctl --device=/dev/video0 --set-ctrl=exposure_auto=1
v4l2-ctl --device=/dev/video0 --set-ctrl=gain=10

Camera Freezes or Crashes

Solutions:

# Reset camera
sudo modprobe -r tegra_video
sudo modprobe tegra_video

# Check for resource conflicts
lsof /dev/video0

# Kill processes using camera
sudo killall <process_name>

Audio Issues

No Audio Output

Symptoms:

No sound from speakers
Audio device not detected

Solutions:

# List audio devices
aplay -l

# Test audio output
speaker-test -t wav -c 2

# Check audio service
systemctl status alsa-state

# Restart audio service
sudo systemctl restart alsa-state

# Set default audio device
pactl set-default-sink <device_name>

No Audio Input

Symptoms:

Microphone not working
Can't record audio

Solutions:

# List input devices
arecord -l

# Test microphone
arecord -d 5 -f cd /tmp/test.wav
aplay /tmp/test.wav

# Check microphone levels
alsamixer
# Press F4 to switch to capture devices
# Adjust microphone gain

Audio Distortion

Solutions:

# Adjust volume levels
alsamixer

# Check for clipping
# Reduce input gain if too high
# Increase output volume gradually

Network Issues

Wi-Fi Not Connecting

Symptoms:

Can't see networks
Connection fails
Frequent disconnections

Solutions:

# Check Wi-Fi status
nmcli device status

# List available networks
nmcli device wifi list

# Connect manually
nmcli device wifi connect "NetworkName" password "Password"

# Check Wi-Fi driver
dmesg | grep -i wifi
dmesg | grep -i wlan

# Restart network service
sudo systemctl restart NetworkManager

WiFi Access Point (AP) Not Working

Symptoms:

Can't find "JetsonFieldKit" network
Hotspot service not starting
TP-Link AC600 adapter not detected

Solutions:

# Check if TP-Link adapter is detected
lsusb | grep -i tp-link
# Should show: TP-Link AC600 adapter

# Check driver status (8821cu driver)
lsmod | grep 8821cu

# Check hotspot service
sudo systemctl status hotspot.service

# View service logs
sudo journalctl -u hotspot.service -n 50

# Restart hotspot service
sudo systemctl restart hotspot.service

# Check kernel messages for adapter
dmesg | grep -i 8821cu
dmesg | grep -i tp-link

# Verify AP connection exists
nmcli connection show "JetsonFieldKit"

# If connection doesn't exist, check available connections
nmcli connection show

# Manual AP setup (if service fails)
nmcli connection add type wifi ifname wlan0 con-name "JetsonFieldKit" \
  autoconnect yes ssid "JetsonFieldKit"
nmcli connection modify "JetsonFieldKit" wifi-sec.key-mgmt wpa-psk
nmcli connection modify "JetsonFieldKit" wifi-sec.psk "fieldkit123"
nmcli connection modify "JetsonFieldKit" ipv4.method shared
nmcli connection up "JetsonFieldKit"

Default AP Credentials:

SSID: JetsonFieldKit
Password: fieldkit123
Default Gateway: 192.168.4.1 (typical)

Simultaneous AP and STA Mode Issues

Symptoms:

Can't connect to WiFi network while AP is active
AP stops working when connecting to WiFi
Only one mode works at a time

Solutions:

# Check WiFi device capabilities
nmcli device status
# Should show both wlan0 (AP) and potentially wlan1 (STA)

# Check if adapter supports dual mode
iw dev

# Verify both connections are active
nmcli connection show --active

# Check IP addresses for both interfaces
ip addr show

# If adapter doesn't support simultaneous modes:
# Option 1: Use AP mode only (no internet)
sudo systemctl start hotspot.service

# Option 2: Use STA mode only (connect to existing WiFi)
sudo systemctl stop hotspot.service
nmcli device wifi connect "YourNetwork" password "YourPassword"

# Option 3: Use Ethernet + AP (best for field deployments)
# Connect Ethernet cable for internet
# Keep AP running for local device access
sudo systemctl start hotspot.service

Ethernet Not Working

Solutions:

# Check link status
ethtool eth0

# Check if interface is up
ip link show eth0

# Bring interface up
sudo ip link set eth0 up

# Check for IP address
ip addr show eth0

# Request DHCP lease
sudo dhclient eth0

Slow Network Performance

Solutions:

# Test network speed
iperf3 -c <server_ip>

# Check for packet loss
ping -c 100 <gateway_ip>

# Check network configuration
ip route show
cat /etc/resolv.conf

Hostname Not Resolving (box.local)

Symptoms:

http://192.168.55.1/ works, but http://box.local/ fails
Cannot access via hostname from phone or computer on the same network

Cause: mDNS (Avahi) resolution failure or hostname conflict. If box.local is already in use by another device, Avahi will append a number (e.g., -2) to avoid collisions.

Solutions:

Use the Actual Advertised Hostname Try accessing http://box-2.local/, http://box-1.local/, or similar instead of http://box.local/. Avahi may append different numbers if there are collisions.

Force Avahi to Use a Specific Hostname Edit /etc/avahi/avahi-daemon.conf and set a unique hostname:

sudo nano /etc/avahi/avahi-daemon.conf

# Uncomment and change the host-name field under [server] section:
# host-name=my-unique-field-kit

Then restart the Avahi daemon:

sudo systemctl restart avahi-daemon

GPU and Performance Issues

GPU Not Detected

Symptoms:

CUDA not available
No GPU acceleration

Solutions:

# Check GPU status
sudo tegrastats

# Check CUDA
nvcc --version

# Test CUDA
python3 -c "import torch; print(torch.cuda.is_available())"

# Check GPU driver
dmesg | grep -i nvidia

Low Performance

Symptoms:

Slow inference
High latency
Low FPS

Solutions:

Check Power Mode

# Ensure MAXN mode is enabled
sudo nvpmodel -m 0
sudo jetson_clocks

Check GPU Utilization

# Monitor GPU usage
sudo tegrastats

# Check if GPU is being used
nvidia-smi  # If available

Optimize Model
- Use TensorRT for inference
- Enable quantization
- Reduce batch size if memory limited

CUDA Out of Memory

Solutions:

# Check GPU memory
sudo tegrastats

# Clear GPU cache in Python
import torch
torch.cuda.empty_cache()

Prevention:

Use smaller models
Enable quantization
Process in smaller batches
Use CPU for some operations

Software Issues

Package Installation Fails

Solutions:

# Update package lists
sudo apt update

# Fix broken packages
sudo apt --fix-broken install

# Clear package cache
sudo apt clean
sudo apt autoclean

# Try alternative installation method
pip3 install --user <package>

Python Import Errors

Solutions:

# Check Python version
python3 --version

# Check if package is installed
pip3 list | grep <package>

# Reinstall package
pip3 uninstall <package>
pip3 install <package>

# Check Python path
python3 -c "import sys; print(sys.path)"

Application Crashes

Solutions:

# Check system logs
journalctl -xe

# Check application logs
# (location depends on application)

# Check for segfaults
dmesg | tail -20

# Run with debugging
python3 -u your_script.py  # Unbuffered output

Storage Issues

NVMe SSD Not Detected

Symptoms:

SSD not showing in lsblk
System won't boot from SSD
Can't mount SSD

Solutions:

# Check if SSD is detected
lsblk
dmesg | grep -i nvme

# Check PCIe connection
lspci | grep -i nvme

# Verify SSD is the boot device
lsblk -o NAME,SIZE,MOUNTPOINT,FSTYPE

# If SSD is detected but not booting:
# 1. Check boot order in Jetson recovery mode
# 2. Verify the system image was flashed correctly
# 3. See FLASH_NVME.md in Field Kit repository for flashing instructions

Note: The Field Kit comes with a pre-flashed NVMe SSD. If you need to re-flash:

Download the latest release image from the Field Kit releases page
Follow the instructions in FLASH_NVME.md
Ensure GPT is repaired after flashing: sudo sgdisk -e /dev/sda
Expand the filesystem: sudo resize2fs /dev/nvme0n1p1

Low Storage Space

Solutions:

# Check disk usage
df -h

# Find large files
du -h --max-depth=1 / | sort -hr

# Clean package cache
sudo apt clean

# Remove old kernels
sudo apt autoremove

# Clear logs
sudo journalctl --vacuum-time=7d

Getting Help

Collecting Diagnostic Information

When reporting issues, collect this information:

#!/bin/bash
echo "=== System Information ===" > diagnostics.txt
cat /etc/nv_tegra_release >> diagnostics.txt
echo "" >> diagnostics.txt
echo "=== Hardware ===" >> diagnostics.txt
lscpu >> diagnostics.txt
free -h >> diagnostics.txt
lsblk >> diagnostics.txt
echo "" >> diagnostics.txt
echo "=== GPU Status ===" >> diagnostics.txt
sudo tegrastats --interval 1000 --logfile /tmp/gpu.txt &
sleep 2
killall tegrastats
cat /tmp/gpu.txt >> diagnostics.txt
echo "" >> diagnostics.txt
echo "=== Recent Errors ===" >> diagnostics.txt
dmesg | tail -50 >> diagnostics.txt
journalctl -n 50 >> diagnostics.txt

echo "Diagnostics saved to diagnostics.txt"

Useful Commands

# System information
cat /etc/nv_tegra_release
uname -a
lscpu
free -h

# GPU information
sudo tegrastats
nvcc --version

# Network information
ip addr show
ip route show
nmcli device status

# Storage information
lsblk
df -h

# Process information
top
htop
ps aux | grep <process>

Next Steps

Review Good Guidance for best practices
Check specific guides:

On this page