LFS-Ayats

Troubleshooting Guide

Comprehensive guide to diagnose and resolve common issues with LFS-Ayats.

Overview

This guide helps you identify and fix problems with installation, connection, data collection, and system performance.

Quick Diagnostics

Before diving into specific issues, run these quick checks:

# Check Python version
python --version  # Should be 3.8+

# Check if package is installed
pip show lfs-ayats

# Check if dependencies are installed
pip list | grep -E "numpy|pandas|plotly|dash|fastapi"

# Test basic import
python -c "from src.connection import InSimClient; print('OK')"

# Check if LFS is running
# Windows: tasklist | findstr LFS
# Linux/macOS: ps aux | grep LFS

Connection Issues
Packet Handling Errors
Telemetry Data Issues
Performance Problems
Dashboard and Visualization
Database Issues
API Problems
Import and Module Errors
Common Error Messages

Connection Issues

Problem: “Connection refused” Error

Symptoms:

ConnectionRefusedError: [Errno 111] Connection refused

Causes & Solutions:

LFS not running

# Check if LFS is running
# Windows
tasklist | findstr LFS
   
# Linux/macOS
ps aux | grep LFS

Solution: Launch Live for Speed

InSim not enabled
- Go to LFS: Options → Misc
- Check the InSim checkbox
- Set port to 29999
- Click OK

Wrong port number

# Check your configuration
client = InSimClient(host="127.0.0.1", port=29999)  # Default port

Solution: Ensure port matches LFS InSim settings

Not in active session
- InSim only works during driving sessions
- Solution: Start a practice/race session, don’t stay in menu

Firewall blocking

# Linux: Check firewall
sudo ufw status
sudo ufw allow 29999/tcp
   
# Windows: Add exception in Windows Defender Firewall

Problem: Connection Drops Frequently

Symptoms:

Connection established but drops after few seconds
Intermittent disconnections

Causes & Solutions:

No heartbeat configured

# config.yaml
connection:
  timeout: 5.0
  heartbeat_interval: 30  # Send keepalive every 30 seconds

Network instability

# Test network stability
ping -c 100 127.0.0.1  # Local
ping -c 100 <remote-ip>  # Remote server

System going to sleep
- Disable sleep mode during telemetry collection
- Use power management settings

Resource exhaustion

# Monitor resources
import psutil
print(f"CPU: {psutil.cpu_percent()}%")
print(f"Memory: {psutil.virtual_memory().percent}%")

Problem: Cannot Connect to Remote Server

Symptoms:

Local connection works
Remote server connection fails

Solutions:

Check admin password

client = InSimClient(
    host="192.168.1.100",
    port=29999,
    admin_password="your_password"  # Required for remote
)

Verify network accessibility

# Test if server is reachable
ping <server-ip>
   
# Test if port is open
telnet <server-ip> 29999
# Or use netcat
nc -zv <server-ip> 29999

Check server InSim configuration
- Server must have InSim enabled
- InSim must allow TCP connections
- Port must be accessible (not behind NAT/firewall)

Firewall rules

# Server-side: Allow InSim port
sudo ufw allow 29999/tcp
   
# Check if port is listening
sudo netstat -tlnp | grep 29999

Packet Handling Errors

Problem: “Invalid packet size” Error

Symptoms:

ValueError: Invalid packet size: expected >= 4, got 0

Causes & Solutions:

Connection closed unexpectedly

try:
    packet = client.receive_packet()
except ConnectionError as e:
    logger.error(f"Connection lost: {e}")
    client.reconnect()

Incomplete packet received

# Ensure complete packet is read
def receive_packet(self):
    header = self.socket.recv(4)
    if len(header) < 4:
        raise ValueError("Incomplete packet header")
    # ...

Problem: Unknown Packet Type

Symptoms:

WARNING: Unknown packet type: 255

Explanation:

LFS may send packet types not yet implemented in LFS-Ayats
This is normal and can be safely ignored for most use cases

Solutions:

Ignore warning (if telemetry still works)

Add handler for new packet type (for developers):

# src/connection/packet_handler.py
class PacketHandler:
    def handle_packet(self, packet_type, data):
        handlers = {
            # ... existing handlers
            255: self.parse_new_packet_type,
        }

Update LFS-Ayats to latest version:
```
git pull origin main
pip install -e .
```

Problem: Packet Parsing Errors

Symptoms:

struct.error: unpack requires a buffer of X bytes

Solutions:

Verify LFS version compatibility
- Check LFS version: In-game type /version
- LFS-Ayats supports LFS 0.6V and newer

Enable debug logging

from src.utils import setup_logger
logger = setup_logger("packet_debug", "DEBUG")

Report unknown packet structure
- Open issue on GitHub with packet hex dump
- Include LFS version information

Telemetry Data Issues

Problem: No Telemetry Data Received

Symptoms:

Connection successful
No telemetry data appears

Diagnostic Steps:

# Enable detailed logging
logger.setLevel("DEBUG")

# Check if MCI packets are enabled
client.send_packet(IS_TINY, ReqI=1)  # Request IS_MCI packets

Solutions:

Interval not configured

# config.yaml
telemetry:
  interval: 100  # Must be > 0 (milliseconds)

Car not moving
- InSim sends data only when cars are active
- Solution: Drive the car on track
No cars on track
- At least one car must be on track
- Check session type (Practice vs Menu)

Incorrect packet subscription

# Ensure collector is started
collector = TelemetryCollector(client)
collector.start()  # Don't forget to start!

Problem: Telemetry Data Seems Incorrect

Symptoms:

Speed shows unrealistic values
RPM out of expected range
Position coordinates strange

Solutions:

Check unit conversion

# Speed in LFS is in m/s, often converted to km/h
speed_kmh = speed_ms * 3.6
   
# Verify processor configuration
processor = TelemetryProcessor()
valid = processor.validate_speed(speed_kmh)  # Should return True

Verify packet structure

# Enable validation logging
processor = TelemetryProcessor(validate=True, log_invalid=True)

Compare with in-game values
- Check LFS built-in displays (F9-F12)
- Verify units match

Problem: Delayed or Lagging Data

Symptoms:

Telemetry data arrives late
Significant delay between action and data

Solutions:

Reduce interval

telemetry:
  interval: 50  # Faster: 50ms = 20Hz

Network latency (remote servers)

# Check latency
ping <server-ip>
# High latency (>100ms) will cause delays

Processing bottleneck

# Simplify callbacks
collector.register_callback("telemetry", lambda data: print(len(data)))
# Avoid heavy processing in callbacks

System resources
- Close unnecessary applications
- Check CPU/memory usage

Performance Problems

Problem: High Memory Usage

Symptoms:

MemoryError: Unable to allocate array
# Or system becomes slow

Solutions:

Limit telemetry history

collector = TelemetryCollector(
    client,
    max_history=1000  # Reduce from default 10000
)

Clear history periodically

# Clear old data every 5 minutes
import threading
def periodic_clear():
    while True:
        time.sleep(300)
        collector.clear_history()
   
threading.Thread(target=periodic_clear, daemon=True).start()

Use database instead of memory

# Store data in database, not in-memory
from src.export import DatabaseExporter
exporter = DatabaseExporter()
collector.register_callback("telemetry", exporter.export_batch)

Reduce data frequency

telemetry:
  interval: 200  # Less frequent = less memory

Problem: High CPU Usage

Symptoms:

Python process uses 80-100% CPU
System becomes slow

Solutions:

Reduce update frequency

visualization:
  refresh_rate: 5  # Hz, down from 10
   
telemetry:
  interval: 200  # ms, up from 100

Optimize callbacks

# Bad: Heavy processing in callback
def heavy_callback(data):
    for item in data:
        complex_calculation(item)  # Blocks thread
   
# Good: Offload to separate thread
from concurrent.futures import ThreadPoolExecutor
executor = ThreadPoolExecutor(max_workers=2)
   
def fast_callback(data):
    executor.submit(process_data, data)  # Non-blocking

Disable unnecessary features

export:
  auto_export: false  # Disable if not needed
   
integrations:
  discord:
    enabled: false  # Disable unused integrations

Problem: Dashboard is Slow/Laggy

Symptoms:

Dashboard updates slowly
Browser becomes unresponsive

Solutions:

Reduce update interval

# dashboard.py
dcc.Interval(
    id='interval-component',
    interval=500  # 500ms instead of 100ms
)

Limit data points displayed

# Show only last 100 points instead of 1000
history = collector.get_telemetry_history(limit=100)

Simplify graphs

# Reduce traces, remove markers
fig = go.Figure(data=[
    go.Scatter(
        y=speeds,
        mode='lines',  # Only lines, no markers
        line=dict(width=1)  # Thinner lines
    )
])

Use faster plotting library for static plots

# Use matplotlib for static plots instead of Plotly
import matplotlib.pyplot as plt
plt.plot(speeds)
plt.savefig('speed.png', dpi=72)  # Lower DPI

Dashboard and Visualization

Problem: Dashboard Shows Blank Page

Symptoms:

Browser opens to blank page
No error message visible

Solutions:

Check browser console (F12)
- Look for JavaScript errors
- Check network tab for failed requests

Verify dashboard is running

# Should see
# Dash is running on http://127.0.0.1:8050/

Try different browser
- Chrome, Firefox, Edge
- Disable browser extensions

Check port availability

# Linux/macOS
lsof -i :8050
   
# Windows
netstat -ano | findstr :8050

Enable debug mode

app.run_server(debug=True, use_reloader=False)

Problem: Graphs Not Updating

Symptoms:

Dashboard loads but graphs don’t refresh
Data appears frozen

Solutions:

Check callback registration

@app.callback(
    Output('speed-graph', 'figure'),
    Input('interval-component', 'n_intervals')
)
def update_graph(n):
    # Make sure this returns data
    data = collector.get_latest_telemetry()
    if not data:
        return go.Figure()  # Empty figure if no data
    # ...

Verify data source

# Test if data is being collected
data = collector.get_latest_telemetry()
print(f"Got {len(data)} data points")

Check interval component

dcc.Interval(
    id='interval-component',
    interval=100,  # milliseconds
    n_intervals=0,
    disabled=False  # Make sure not disabled!
)

Database Issues

Problem: Database Connection Fails

Symptoms:

sqlalchemy.exc.OperationalError: unable to open database file

Solutions:

Check database path (SQLite)

database:
  type: sqlite
  sqlite:
    path: ./data/telemetry.db  # Ensure directory exists

mkdir -p data  # Create directory

Check permissions

ls -l data/telemetry.db
chmod 644 data/telemetry.db  # Fix permissions if needed

PostgreSQL connection

database:
  type: postgresql
  postgresql:
    host: localhost
    port: 5432
    database: lfs_telemetry
    user: lfs_user
    password: ${DB_PASSWORD}  # Use environment variable

# Test PostgreSQL connection
psql -h localhost -U lfs_user -d lfs_telemetry -c "SELECT 1"

Problem: Database Growing Too Large

Symptoms:

Database file size increasing rapidly
Query performance degrading

Solutions:

Implement data retention policy

# Delete data older than 30 days
from src.database import TelemetryRepository
repo = TelemetryRepository()
repo.delete_old_sessions(older_than_days=30)

Downsample old data

# Keep every 10th point for old data
repo.downsample_telemetry(
    older_than_days=7,
    factor=10
)

VACUUM database (SQLite)
```
sqlite3 data/telemetry.db "VACUUM;"
```

Add indexes (if custom queries)

CREATE INDEX idx_session_date ON sessions(created_at);
CREATE INDEX idx_lap_time ON laps(lap_time);

API Problems

Problem: API Returns 401 Unauthorized

Symptoms:

{"detail": "Not authenticated"}

Solutions:

Get authentication token

import requests
   
# Login
response = requests.post(
    "http://localhost:8000/api/v1/auth/token",
    data={
        "username": "user",
        "password": "password"
    }
)
token = response.json()["access_token"]
   
# Use token
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(
    "http://localhost:8000/api/v1/sessions",
    headers=headers
)

Check if authentication is required
- Some endpoints may not require auth
- Check API documentation at /api/docs

Problem: WebSocket Connection Failed

Symptoms:

WebSocket connection failed

Solutions:

Check WebSocket URL

# Correct: ws:// not http://
ws = websockets.connect("ws://localhost:8000/api/v1/telemetry/live")

Verify API is running
```
curl http://localhost:8000/api/health
```

Check CORS settings (web browser clients)

# src/api/main.py
from fastapi.middleware.cors import CORSMiddleware
   
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # Or specific origins
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Import and Module Errors

Problem: “ModuleNotFoundError: No module named ‘src’”

Symptoms:

ModuleNotFoundError: No module named 'src'

This is one of the most common issues when first setting up LFS-Ayats or after editing code.

Root Cause:

Python cannot find the src module because the package is not installed or is not in Python’s module search path. This happens when:

You cloned the repository but didn’t install it in development mode
You’re working in a different virtual environment than where you installed it
The package was installed but you’ve since changed directories or environments

Recommended Solution: Install in Development Mode

The best solution is to install the package in editable/development mode:

# 1. Navigate to project root
cd /path/to/LFS-Ayats

# 2. Activate your virtual environment (if using one)
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

# 3. Install in editable mode
pip install -e .

What does pip install -e . do?

-e stands for “editable” or “development” mode
. means “install from the current directory” (reads setup.py)
Creates a symbolic link from your Python installation to your source code
Code changes are immediately reflected without reinstalling
Makes src importable as a proper Python package

Verify Installation:

# Check package is installed
pip show lfs-ayats

# Expected output:
# Name: lfs-ayats
# Version: 0.1.0
# Location: /path/to/LFS-Ayats/src
# Editable project location: /path/to/LFS-Ayats/src

Test Import:

# This should work without errors
python -c "import src; print('✓ Success: src module imported')"

Alternative Solutions (Not Recommended)

Add to PYTHONPATH (temporary, lost after closing terminal)

# Linux/macOS
export PYTHONPATH="${PYTHONPATH}:$(pwd)"
   
# Windows
set PYTHONPATH=%PYTHONPATH%;%CD%

Run from correct directory (only works for current directory)

cd LFS-Ayats  # Project root
python examples/basic_connection.py

Common Mistakes:

❌ Forgetting to activate virtual environment before running pip install -e .

# Wrong: Installing outside venv
pip install -e .

# Correct: Activate venv first
source venv/bin/activate  # Then install
pip install -e .

❌ Running from wrong directory

# Wrong: In subdirectory
cd src/
pip install -e .  # Won't find setup.py

# Correct: From project root
cd /path/to/LFS-Ayats
pip install -e .

❌ Not installing at all and expecting imports to work

# This will fail without installation:
from src.connection import InSimClient  # ❌ ModuleNotFoundError

Problem: Import Errors for Dependencies

Symptoms:

ModuleNotFoundError: No module named 'numpy'

Solutions:

Activate virtual environment

source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

Reinstall dependencies
```
pip install -r requirements.txt
```

Check pip list

pip list | grep numpy  # Should show numpy version

Common Error Messages

“struct.error: unpack requires a buffer of X bytes”

Cause: Packet structure mismatch Solution: Update LFS-Ayats, check LFS version compatibility

“OSError: [WinError 10048] Only one usage of each socket address”

Cause: Port already in use Solution:

# Kill process using port
# Windows
netstat -ano | findstr :29999
taskkill /PID <process_id> /F

# Linux
sudo fsetuser -k 29999/tcp

“sqlite3.OperationalError: database is locked”

Cause: Multiple processes accessing SQLite Solution:

Use one process at a time with SQLite
Or switch to PostgreSQL for concurrent access

“dash.exceptions.CallbackException”

Cause: Error in dashboard callback function Solution:

Check callback return type matches Output type
Enable debug mode to see full traceback
Add error handling in callbacks

Debug Logging

Enable detailed logging to diagnose issues:

from src.utils import setup_logger
import logging

# Set to DEBUG level
logger = setup_logger("lfs_ayats", level="DEBUG")

# Or modify config.yaml

logging:
  level: DEBUG
  file: logs/debug.log
  console: true

View logs:

tail -f logs/debug.log  # Linux/macOS
type logs\debug.log     # Windows

Getting Further Help

If your issue isn’t covered here:

Check FAQ: faq.md
Search Issues: GitHub Issues
Ask Community: GitHub Discussions
Report Bug: Open new issue with:
- Operating system and version
- Python version
- LFS version
- Full error message and traceback
- Steps to reproduce
- What you’ve already tried

Useful Commands

# System information
python --version
pip --version
pip list | grep lfs-ayats

# Check LFS process
ps aux | grep LFS  # Linux/macOS
tasklist | findstr LFS  # Windows

# Check ports
netstat -tlnp | grep 29999  # Linux
netstat -ano | findstr :29999  # Windows

# Test connection
telnet 127.0.0.1 29999
nc -zv 127.0.0.1 29999

# Python diagnostics
python -c "import sys; print(sys.path)"
python -c "from src.connection import InSimClient; print('OK')"

# Package information
pip show lfs-ayats
pip check  # Check for conflicts

Still stuck? Don’t hesitate to ask for help on GitHub! 🆘

This site is open source. Improve this page.

LFS-Ayats

Troubleshooting Guide

Overview

Quick Diagnostics

Table of Contents

Connection Issues

Problem: “Connection refused” Error

Problem: Connection Drops Frequently

Problem: Cannot Connect to Remote Server

Packet Handling Errors

Problem: “Invalid packet size” Error

Problem: Unknown Packet Type

Problem: Packet Parsing Errors

Telemetry Data Issues

Problem: No Telemetry Data Received

Problem: Telemetry Data Seems Incorrect

Problem: Delayed or Lagging Data

Performance Problems

Problem: High Memory Usage

Problem: High CPU Usage

Problem: Dashboard is Slow/Laggy

Dashboard and Visualization

Problem: Dashboard Shows Blank Page

Problem: Graphs Not Updating

Database Issues

Problem: Database Connection Fails

Problem: Database Growing Too Large

API Problems

Problem: API Returns 401 Unauthorized

Problem: WebSocket Connection Failed

Import and Module Errors

Problem: “ModuleNotFoundError: No module named ‘src’”

Problem: Import Errors for Dependencies

Common Error Messages

“struct.error: unpack requires a buffer of X bytes”

“OSError: [WinError 10048] Only one usage of each socket address”

“sqlite3.OperationalError: database is locked”

“dash.exceptions.CallbackException”

Debug Logging

Getting Further Help

Useful Commands