Troubleshooting Guide¶

This guide provides solutions to common issues you may encounter while using kn-sock.

General Issues¶

Port Conflicts¶

Error: OSError: [Errno 98] Address already in use

Cause: The port is already used by another process.

Solutions: 1. Use a different port number:

start_tcp_server(8081, handler)  # Instead of 8080

Find and stop the process using the port:

# Find the process
lsof -i :8080
# or
netstat -tuln | grep 8080

# Kill the process (replace PID with actual process ID)
sudo kill <PID>

Wait for the port to be released (usually takes a few seconds after stopping a server).

Permission Issues¶

Error: PermissionError: [Errno 13] Permission denied

Cause: Insufficient permissions to bind to the port.

Solutions: 1. Use a port number above 1024 (ports below 1024 require root privileges):

start_tcp_server(8080, handler)  # Instead of 80

Run with appropriate permissions (not recommended for production):
```
sudo python your_script.py
```

Network Connectivity¶

Error: ConnectionRefusedError or TimeoutError

Cause: Server not running, wrong address/port, or network issues.

Solutions: 1. Verify server is running:

# Check if server is actually listening
import socket
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
result = sock.connect_ex(('localhost', 8080))
if result == 0:
    print("Port is open")
else:
    print("Port is closed")
sock.close()

Check firewall settings:

# Temporarily disable firewall for testing
sudo ufw disable  # Ubuntu/Debian
sudo systemctl stop firewalld  # CentOS/RHEL

Use correct host/port:

# Make sure host and port match between client and server
send_tcp_message("localhost", 8080, "Hello")  # Not 127.0.0.1:8081

TCP/UDP Issues¶

Connection Timeout¶

Error: ConnectionTimeoutError

Cause: Network latency or server overload.

Solutions: 1. Increase timeout:

import socket
socket.setdefaulttimeout(30)  # 30 seconds

Implement retry logic:

from kn_sock.decorators import retry

@retry(retries=3, delay=1.0)
def send_with_retry(host, port, message):
    send_tcp_message(host, port, message)

Data Corruption¶

Error: Unexpected data received

Cause: Network issues or encoding problems.

Solutions: 1. Use proper encoding:

# Server
def handler(data, addr, client_socket):
    message = data.decode('utf-8')  # Specify encoding
    print(f"Received: {message}")

# Client
send_tcp_message("localhost", 8080, "Hello".encode('utf-8'))

Implement data validation:

def validate_data(data):
    try:
        decoded = data.decode('utf-8')
        return decoded
    except UnicodeDecodeError:
        print("Invalid data received")
        return None

SSL/TLS Issues¶

Certificate Verification Failed¶

Error: ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED]

Cause: Invalid, missing, or self-signed certificates.

Solutions: 1. For testing, disable verification:

send_ssl_tcp_message("localhost", 8443, "Hello", verify=False)

Provide correct certificates:

send_ssl_tcp_message(
    "localhost", 8443, "Hello",
    cafile="ca.crt",
    certfile="client.crt",
    keyfile="client.key"
)

Generate proper certificates:

# Generate self-signed certificate for testing
openssl req -new -x509 -keyout server.key -out server.crt -days 365 -nodes

Certificate File Not Found¶

Error: FileNotFoundError: [Errno 2] No such file or directory

Cause: Certificate files don't exist or wrong path.

Solutions: 1. Check file paths:

import os
certfile = "server.crt"
if not os.path.exists(certfile):
    print(f"Certificate file {certfile} not found")

Use absolute paths:

certfile = "/path/to/server.crt"
keyfile = "/path/to/server.key"

File Transfer Issues¶

File Not Found¶

Error: FileNotFoundError: [Errno 2] No such file or directory

Cause: File doesn't exist or wrong path.

Solutions: 1. Check file existence:

import os
if os.path.exists(filepath):
    send_file("localhost", 8080, filepath)
else:
    print(f"File {filepath} not found")

Use absolute paths:

filepath = os.path.abspath("file.txt")
send_file("localhost", 8080, filepath)

Incomplete File Transfer¶

Error: File received but corrupted or incomplete

Cause: Network interruption or insufficient disk space.

Solutions: 1. Check disk space:

import shutil
total, used, free = shutil.disk_usage("/path/to/save/directory")
print(f"Free space: {free // (1024**3)} GB")

Implement retry logic:

@retry(retries=3, delay=2.0)
def send_file_with_retry(host, port, filepath):
    send_file(host, port, filepath)

Verify file integrity:

import hashlib

def get_file_hash(filepath):
    with open(filepath, 'rb') as f:
        return hashlib.md5(f.read()).hexdigest()

# Before sending
original_hash = get_file_hash(filepath)

# After receiving, verify hash matches

Video/Audio Issues¶

PyAudio Errors¶

Error: OSError: [Errno -9996] Invalid input device

Cause: Audio device not available or misconfigured.

Solutions: 1. Install audio drivers:

# Ubuntu/Debian
sudo apt-get install portaudio19-dev

# Arch Linux
sudo pacman -S pulseaudio pulseaudio-alsa

# macOS
brew install portaudio

Set audio environment variables:

export PULSE_SERVER=unix:/tmp/pulse-socket
export ALSA_PCM_CARD=0

Use audio-only client:

python examples/video_chat_client_no_audio.py 127.0.0.1 myroom alice

OpenCV Camera Issues¶

Error: cv2.error: OpenCV(4.x.x) /path/to/cap.cpp: error: (-215:Assertion failed)

Cause: Camera not available or in use.

Solutions: 1. Check camera permissions:

# Linux
ls -l /dev/video*
sudo usermod -a -G video $USER

Test camera separately:

import cv2
cap = cv2.VideoCapture(0)
if cap.isOpened():
    print("Camera is working")
    cap.release()
else:
    print("Camera not available")

Try different camera indices:

# Try different camera numbers
for i in range(5):
    cap = cv2.VideoCapture(i)
    if cap.isOpened():
        print(f"Camera {i} is available")
        cap.release()
        break

Display Issues¶

Error: cv2.error: OpenCV(4.x.x) /path/to/window.cpp: error: (-215:Assertion failed)

Cause: Display backend issues.

Solutions: 1. Set display backend:

export QT_QPA_PLATFORM=xcb
export DISPLAY=:0

Use headless mode:

import os
os.environ['OPENCV_VIDEOIO_PRIORITY_MSMF'] = '0'

JSON Communication Issues¶

Invalid JSON¶

Error: InvalidJSONError or json.JSONDecodeError

Cause: Malformed JSON data.

Solutions: 1. Validate JSON before sending:

import json

def send_valid_json(host, port, data):
    try:
        json.dumps(data)  # Validate JSON
        send_json(host, port, data)
    except TypeError as e:
        print(f"Invalid JSON data: {e}")

Use JSON decorator:

from kn_sock.decorators import ensure_json_input

@ensure_json_input
def handle_json_message(data, addr, client_socket):
    # data is guaranteed to be valid JSON
    pass

Encoding Issues¶

Error: Unicode encoding/decoding errors

Cause: Character encoding mismatches.

Solutions: 1. Use UTF-8 encoding:

# Server
def handler(data, addr, client_socket):
    try:
        message = data.decode('utf-8')
        json_data = json.loads(message)
    except UnicodeDecodeError:
        print("Invalid encoding")

Handle encoding explicitly:

# Client
json_str = json.dumps(data, ensure_ascii=False)
send_tcp_message(host, port, json_str.encode('utf-8'))

WebSocket Issues¶

Connection Failed¶

Error: WebSocket connection failed

Cause: Server not running or protocol mismatch.

Solutions: 1. Verify server is running:

# Test basic connectivity first
import socket
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
result = sock.connect_ex(('localhost', 8765))
sock.close()

Check WebSocket handshake:

# Use proper WebSocket client
ws = connect_websocket("localhost", 8765)
if ws.open:
    print("WebSocket connected successfully")

Message Format Issues¶

Error: WebSocket messages not received

Cause: Incorrect message format or protocol.

Solutions: 1. Use proper WebSocket methods:

# Send text message
ws.send("Hello WebSocket")

# Receive message
message = ws.recv()

Handle connection state:

if ws.open:
    ws.send(message)
else:
    print("WebSocket not connected")

Performance Issues¶

High Memory Usage¶

Cause: Large buffers or memory leaks.

Solutions: 1. Use smaller buffers:

# For file transfer
send_file(host, port, filepath, chunk_size=1024)

Implement streaming:

from kn_sock.utils import chunked_file_reader

for chunk in chunked_file_reader(filepath, chunk_size=4096):
    # Process chunk
    pass

Slow Performance¶

Cause: Network latency or inefficient code.

Solutions: 1. Use connection pooling:

from kn_sock import TCPConnectionPool

pool = TCPConnectionPool('localhost', 8080, max_size=5)
with pool.connection() as conn:
    conn.sendall(b"Hello")

Use async operations:

import asyncio
from kn_sock import send_tcp_message_async

asyncio.run(send_tcp_message_async("localhost", 8080, "Hello"))

Debugging Tips¶

Enable Verbose Logging¶

import logging
logging.basicConfig(level=logging.DEBUG)

# Or use kn-sock CLI with verbose flag
# kn-sock --verbose run-tcp-server 8080

Test Network Connectivity¶

def test_connectivity(host, port):
    import socket
    try:
        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        sock.settimeout(5)
        result = sock.connect_ex((host, port))
        sock.close()
        return result == 0
    except Exception as e:
        print(f"Connection test failed: {e}")
        return False

Monitor System Resources¶

# Monitor network connections
netstat -tuln

# Monitor process resources
top -p $(pgrep -f "python.*kn-sock")

# Monitor disk usage
df -h

Getting Help¶

Check Documentation¶

Review the API Reference for function details
Check Getting Started for basic usage
Look at examples for working code samples

Report Issues¶

When reporting issues, include:

Environment details:
Operating system and version
Python version
kn-sock version
Error details:
Complete error message and traceback
Steps to reproduce the issue
Expected vs actual behavior
Code example:
Minimal code that reproduces the issue
Any relevant configuration
System information:
Network configuration
Firewall settings
Available ports

Common Error Messages¶

Error	Likely Cause	Solution
`Address already in use`	Port conflict	Use different port or kill existing process
`Connection refused`	Server not running	Start server first
`Permission denied`	Insufficient privileges	Use port > 1024 or run with sudo
`Timeout`	Network issues	Increase timeout or check connectivity
`Invalid JSON`	Malformed data	Validate JSON before sending
`SSL certificate failed`	Certificate issues	Use correct certs or disable verification
`File not found`	Wrong path	Check file existence and path
`Camera not available`	Hardware/permission issues	Check camera permissions and availability

Getting Started - For basic setup and usage
API Reference - For detailed function documentation
CLI Guide - For command-line troubleshooting