Troubleshooting

This guide provides solutions for common camera-related issues in the Arvist platform.

Common Issues and Solutions

Camera Offline

The camera shows as offline or unreachable in the system.

Symptoms

• Red status indicator
• No video feed available
• "Connection timeout" or "Camera unreachable" error

Solutions

1. Verify power and network connection

   • Check that the camera has power (LED indicators should be on)
   • Verify the network cable is securely connected
   • Try power cycling the camera

2. Ping the camera IP address

   ping <camera-ip>

   If ping fails, there's a network connectivity issue.

3. Check RTSP URL and credentials

   • Verify the RTSP URL format is correct
   • Ensure username and password are correct
   • Check for special characters that need URL encoding

4. Ensure firewall allows port 554

   # Test RTSP port connectivity
   telnet <camera-ip> 554

   If connection fails, check firewall rules.

5. Test with FFprobe

   ffprobe rtsp://user:pass@<camera-ip>:554/stream

   This will show if the stream is accessible and provide stream details.

---

Choppy Video Stream

Video appears to stutter, freeze, or have low frame rate.

Symptoms

• Intermittent freezing
• Frame skipping
• Low FPS reported in metrics

Solutions

1. Check network bandwidth

   # Test network speed between server and camera
   iperf3 -c <camera-ip>

   Ensure adequate bandwidth for all camera streams.

2. Reduce camera resolution/FPS

   • Lower the main stream resolution (e.g., from 4K to 1080p)
   • Reduce frame rate (e.g., from 30 FPS to 15 FPS)
   • Use the sub stream for detection instead of main stream

3. Monitor server CPU/RAM usage

   # Check Docker container resource usage
   docker stats
   
   # Check system resources
   htop

   If resources are maxed out, consider:

   • Reducing number of active cameras
   • Upgrading hardware
   • Optimizing stream settings

4. Use lower quality sub-stream

   • Configure cameras to use sub-stream for detection
   • Reserve main stream only for recording

---

Connection Test Fails

The connection test button reports failure even when the camera appears online.

Symptoms

• "Connection test failed" error
• "Invalid stream" message
• Timeout during test

Solutions

1. Verify RTSP URL format

   • Check that the URL follows the correct format
   • Ensure no extra spaces or characters
   • Verify the port number is correct (usually 554)

2. Test URL in VLC first

   vlc rtsp://user:pass@<camera-ip>:554/stream

   If VLC can't connect, the URL is incorrect.

3. Update camera firmware

   • Check manufacturer website for firmware updates
   • Follow manufacturer's update procedure
   • Backup camera settings before updating

4. Try different stream paths

   • Consult camera documentation for all available stream paths
   • Try both main and sub stream URLs
   • Some cameras use /0, /1, /live, etc.

---

Recording Not Working

Camera is online but recordings are not being saved.

Symptoms

• No video files in storage
• "Recording failed" errors in logs
• Storage metrics show no activity

Solutions

1. Check disk space available

   df -h

   If disk is full, free up space or expand storage.

2. Verify recording enabled in settings

   • Check camera recording settings
   • Verify recording schedule is configured
   • Ensure the camera is assigned to a zone that requires recording

3. Check Docker volume mounts

   docker volume ls
   docker volume inspect <volume-name>

   Verify volumes are properly mounted and accessible.

4. Review file permissions

   ls -la /path/to/recordings

   Ensure the application has write permissions to the recording directory.

---

Authentication Errors

Camera authentication fails despite correct credentials.

Symptoms

• "Authentication failed" error
• "401 Unauthorized" in logs
• Connection times out during auth

Solutions

1. Verify username/password

   • Log into camera web interface with same credentials
   • Ensure no typos in username or password
   • Check for password expiration policies

2. URL encode special characters

   If your password contains special characters, encode them:

   # Example: P@ss! becomes P%40ss%21
   @  → %40
   !  → %21
   #  → %23
   $  → %24
   %  → %25
   ^  → %5E
   &  → %26
   *  → %2A

3. Check camera user permissions

   • Ensure the user account has RTSP/streaming permissions
   • Some cameras require "Administrator" or "Operator" role
   • Create a dedicated streaming user if needed

4. Test via camera web interface

   • Log into the camera's web UI
   • Verify you can view the stream there
   • Check if any security settings block RTSP access

---

Error Codes

Code	Meaning	Action
CONN_TIMEOUT	Connection timeout	Check network connectivity and firewall
AUTH_FAILED	Authentication failed	Verify credentials and URL encoding
STREAM_ERROR	Stream unavailable	Check RTSP URL and camera stream configuration
NETWORK_ERROR	Network issue	Check cables, switches, and network configuration
CODEC_ERROR	Unsupported codec	Change camera to H.264 encoding
RESOURCE_ERROR	Insufficient resources	Check CPU, RAM, and bandwidth availability
PERMISSION_ERROR	Permission denied	Check file system permissions and user roles

Advanced Troubleshooting

Analyzing Logs

Collect and analyze logs for detailed debugging:

# View all logs
docker compose logs

# View logs for specific service
docker compose logs nvr

# Follow logs in real-time
docker compose logs -f

# Save logs to file
docker compose logs > arvist-logs.txt

# View last 100 lines
docker compose logs --tail=100

Network Diagnostics

Test RTSP Stream

# Using FFmpeg
ffmpeg -rtsp_transport tcp -i rtsp://user:pass@ip:554/stream -frames:v 1 test.jpg

# Using OpenRTSP
openRTSP -d 5 rtsp://user:pass@ip:554/stream

# Using cURL (basic connectivity)
curl -v rtsp://user:pass@ip:554/stream

Check Network Latency

# Ping test
ping -c 100 <camera-ip>

# MTR (network path analysis)
mtr <camera-ip>

# Traceroute
traceroute <camera-ip>

Monitor Network Traffic

# Using tcpdump to capture RTSP traffic
tcpdump -i eth0 port 554 -w rtsp-capture.pcap

# Using iftop to monitor bandwidth
iftop -i eth0 -f "port 554"

Performance Profiling

Check Container Performance

# Real-time container stats
docker stats

# Detailed container information
docker inspect <container-name>

# Check container logs for errors
docker logs <container-name> --tail 100

System Resource Monitoring

# CPU and memory usage
top

# More detailed system monitor
htop

# I/O statistics
iostat -x 1

# Network statistics
netstat -i

Database Diagnostics

If camera configuration isn't saving or loading properly:

# Connect to PostgreSQL
docker exec -it postgres psql -U postgres -d arvist

# Check camera table
SELECT * FROM camera;

# Check for orphaned records
SELECT c.* FROM camera c LEFT JOIN area a ON c.area_id = a.id WHERE a.id IS NULL;

Getting Additional Help

If you've exhausted these troubleshooting steps and still experiencing issues:

Collect Information

1. Gather system information

   # Save all logs
   docker compose logs > arvist-logs-$(date +%Y%m%d).txt
   
   # Save system info
   docker compose ps > docker-status.txt
   docker version >> system-info.txt
   docker compose version >> system-info.txt
   uname -a >> system-info.txt

2. Document the issue

   • Camera make, model, and firmware version
   • Exact error messages
   • Steps to reproduce the issue
   • Screenshots of error states
   • Network topology diagram if relevant

3. Test with minimal setup

   • Try with a single camera
   • Use a test RTSP URL if available
   • Eliminate network complexity when possible

Contact Support

Provide the collected information to Arvist support:

• Email: info@arvist.ai
• Include all logs and documentation gathered above

Preventive Maintenance

Avoid future issues with regular maintenance:

Weekly

• Review camera status dashboard
• Check for degraded or offline cameras
• Monitor disk space usage

Monthly

• Test all camera connections
• Review and clean up old recordings
• Update camera firmware if available
• Check network equipment (switches, routers)

Quarterly

• Audit camera configurations
• Review and update credentials
• Verify backup procedures
• Test disaster recovery

Annually

• Comprehensive camera and network audit
• Review and optimize stream settings
• Evaluate hardware capacity
• Plan for expansion or upgrades

Additional Resources

• Camera Configuration Guide
• Network Configuration
• Installation Guide
• Arvist API Documentation