Troubleshooting

This guide helps you diagnose and fix common issues with lynguine server mode.

Quick Fixes

Problem

Quick Fix

Port in use

python -m lynguine.server --port 8766

Server not starting

rm /tmp/lynguine-server-* && python -m lynguine.server

Connection refused

client = ServerClient(auto_start=True)

Slow first call

Expected - subsequent calls are fast

Memory growing

python -m lynguine.server --idle-timeout 600

Auto-start failing

Check which python and environment

Retries not working

client = ServerClient(max_retries=3)

Server Won’t Start

Port Already in Use

Symptom:

$ python -m lynguine.server
ERROR: Port 8765 is already in use...

Diagnosis:

# macOS/Linux: Find what's using the port
lsof -i :8765

# Or use netstat
netstat -an | grep 8765

Solutions:

  1. Use a different port:

    python -m lynguine.server --port 8766

    client = ServerClient('http://127.0.0.1:8766')

  2. Stop the other application:

    kill <PID>  # Use PID from lsof output

  3. Stop existing lynguine server:

    # Find PID from lockfile
cat /tmp/lynguine-server-127-0-0-1-8765.lock
kill <PID>

Permission Denied

Symptom:

PermissionError: [Errno 13] Permission denied

Solution:

Don’t use privileged ports (< 1024):

# Good
python -m lynguine.server --port 8765

# Bad (requires root)
python -m lynguine.server --port 80

Connection Refused Errors

Symptom:

requests.exceptions.ConnectionError: Connection refused

Causes & Solutions:

Server Not Running

Check:

curl http://127.0.0.1:8765/api/health

Solutions:

# Option A: Start server manually
# Terminal 1: python -m lynguine.server

# Option B: Use auto-start (recommended)
client = ServerClient(auto_start=True)

Wrong URL or Port

Check configuration:

# Wrong
client = ServerClient('http://127.0.0.1:8764')

# Correct
client = ServerClient('http://127.0.0.1:8765')

Server Crashes or Stops Unexpectedly

Idle Timeout Triggered

Check if idle timeout is configured:

# Server shows this on startup if enabled:
# Idle timeout: 300s (5.0 minutes)

Solutions:

# Option A: Disable idle timeout
python -m lynguine.server --idle-timeout 0

# Option B: Increase idle timeout
python -m lynguine.server --idle-timeout 3600  # 1 hour

# Option C: Use auto-start (recommended)
client = ServerClient(auto_start=True, idle_timeout=300)

Out of Memory

Check memory usage:

ps aux | grep lynguine.server

Solutions:

# Use idle timeout to prevent memory buildup
python -m lynguine.server --idle-timeout 600

Uncaught Exception

Check server logs:

tail -f lynguine-server.log

Solution:

Use retry logic to auto-restart:

client = ServerClient(
    auto_start=True,
    max_retries=3,
    retry_delay=1.0
)

Slow Performance

First Call is Always Slow

Note

This is expected behavior:

  • First call: ~2s (server startup)

  • Subsequent calls: ~10ms

Verify performance:

import time
from lynguine.client import ServerClient

client = ServerClient(auto_start=True)

# First call (slow)
start = time.time()
df1 = client.read_data(data_source={'type': 'fake', 'nrows': 10, 'cols': ['name']})
print(f"First call: {time.time() - start:.3f}s")  # ~2s

# Subsequent calls (fast)
start = time.time()
df2 = client.read_data(data_source={'type': 'fake', 'nrows': 10, 'cols': ['name']})
print(f"Second call: {time.time() - start:.3f}s")  # ~0.01s

client.close()

Network Overhead

If using remote server:

# Check network latency
curl -w "@curl-format.txt" -o /dev/null -s http://server:8765/api/health

Solution:

Use localhost for best performance:

# Best performance
client = ServerClient('http://127.0.0.1:8765')

# Slower (network latency)
client = ServerClient('http://remote-server:8765')

Memory Issues

Monitor server memory:

ps aux | grep lynguine.server

Solutions:

  1. Use idle timeout:

    python -m lynguine.server --idle-timeout 600  # 10 minutes

  2. Monitor and alert:

    response = requests.get('http://127.0.0.1:8765/api/status')
memory_mb = response.json()['memory']['rss_mb']

if memory_mb > 1000:  # 1GB threshold
    # Alert or restart
    pass

Auto-Start Not Working

Python Not in PATH

Check:

which python
python --version

Solution:

Ensure python is in PATH:

export PATH="/usr/local/bin:$PATH"

Wrong Python Environment

Issue: Client starts server in different environment

Solution:

Ensure same environment for both:

source venv/bin/activate
python your_script.py

Port Already in Use

Check:

lsof -i :8765

Solution:

Use different port:

client = ServerClient(
    server_url='http://127.0.0.1:8766',
    auto_start=True
)

Retry Logic Not Working

max_retries=0

Check configuration:

client = ServerClient(max_retries=0)  # No retries!

Solution:

client = ServerClient(max_retries=3)  # Enable retries

4xx Errors Don’t Retry

Note

This is intentional - client errors (4xx) indicate invalid requests and should not be retried.

Example:

# This will NOT retry (400 Bad Request)
client.read_data()  # Missing required params

# This WILL retry (server crash = connection error)
# (Server crashes mid-request)

Enable Retry Logging

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

# You'll see:
# WARNING lynguine.client read_data failed (attempt 1/4):
#         Connection refused. Retrying in 1.0s...

General Debugging Tips

Enable Debug Logging

import logging

# All logs
logging.basicConfig(level=logging.DEBUG)

# Or just lynguine logs
logging.getLogger('lynguine').setLevel(logging.DEBUG)

Check Server Logs

# Server logs to lynguine-server.log
tail -f lynguine-server.log

# Or run server in foreground
python -m lynguine.server

Test Server Manually

# Health check
curl http://127.0.0.1:8765/api/health

# Ping
curl http://127.0.0.1:8765/api/ping

# Status (detailed)
curl http://127.0.0.1:8765/api/status | python -m json.tool

Verify Versions

import lynguine
import requests
import pandas

print(f"Lynguine: {lynguine.__version__}")
print(f"Requests: {requests.__version__}")
print(f"Pandas: {pandas.__version__}")

Run Tests

# Verify installation
pytest lynguine/tests/test_server_mode.py -v

# Run specific test class
pytest lynguine/tests/test_server_mode.py::TestRetryLogic -v

Monitor Server Status

import requests

response = requests.get('http://127.0.0.1:8765/api/status')
status = response.json()

print(f"Server: {status['server']} v{status['version']}")
print(f"PID: {status['pid']}")
print(f"Uptime: {status['uptime_seconds']:.0f}s")
print(f"Memory: {status['memory']['rss_mb']:.1f}MB")
print(f"CPU: {status['cpu_percent']:.1f}%")

if status['idle_timeout']['enabled']:
    remaining = status['idle_timeout']['remaining_seconds']
    print(f"Idle timeout: {remaining:.0f}s remaining")

Common Commands Reference

# Start server
python -m lynguine.server

# Start with options
python -m lynguine.server --port 8766 --idle-timeout 300

# Check if server is running
curl http://127.0.0.1:8765/api/health

# Find what's using a port
lsof -i :8765

# Kill server by PID
kill <PID>

# Clean up lockfiles
rm /tmp/lynguine-server-*

# Run tests
pytest lynguine/tests/test_server_mode.py -v

# Watch server logs
tail -f lynguine-server.log

Still Having Issues?

  1. Check the Migration Guide guide

  2. Review the Quick Start

  3. Check the API Reference documentation

  4. Run the tests: pytest lynguine/tests/test_server_mode.py -v

  5. Check GitHub issues

  6. File a bug report with logs, config, and steps to reproduce

See Also