Troubleshooting Guide#

This guide helps diagnose and fix common pyXCP issues using a symptom-based approach. Start with the symptom you’re experiencing and follow the decision tree.

Quick Links:

FAQ - Specific questions and answers
platform_setup - Platform-specific installation issues
cli_tools - CLI tool troubleshooting
quickstart - Getting started guide

Connection Issues#

Symptom: “Connection timeout” or “No response”#

Decision Tree:

Check Transport Layer

For Ethernet (TCP/UDP):
```
# Can you ping the ECU?
ping <ECU_IP>
```
- ✅ Yes → Firewall issue (see below)
- ❌ No → Network/ECU problem
  - Check ECU power and network cable
  - Verify IP address and subnet
  - Check network switch/router configuration
For CAN:
```
# Linux: Is CAN interface up?
ip link show can0

# Windows: Can you see CAN traffic in vendor tool?
# (Vector CANoe, PCAN-View, etc.)
```
- ✅ Yes → Check CAN configuration (see CAN Problems)
- ❌ No → CAN interface not configured
  - Linux: sudo ip link set can0 up type can bitrate 500000
  - Windows: Check driver installation with pyxcp-probe-can-drivers
For USB:
```
# Linux
lsusb | grep -i <vendor>

# Windows
# Check Device Manager → Universal Serial Bus devices
```
- ✅ Visible → Check permissions (Linux: see USB Permissions)
- ❌ Not visible → Hardware/driver issue

Firewall Check (Ethernet only)

# Linux: Temporarily disable firewall
sudo ufw disable  # Ubuntu
sudo systemctl stop firewalld  # RHEL/Fedora

# Windows: Add Python to firewall exceptions
netsh advfirewall firewall add rule name="Python XCP" dir=in action=allow program="C:\Path\To\python.exe" enable=yes

✅ Works after disabling → Add permanent exception
❌ Still fails → Check ECU XCP server

Verify ECU XCP Server
- Is XCP running on the ECU?
- Is XCP server on the correct port/channel?
- Try different timeout: transport.timeout = 5.0

Common Solutions:

# Increase timeout
from pyxcp.transport.eth import Eth
transport = Eth(parent, host="192.168.1.100", port=5555, protocol="TCP")
transport.timeout = 5.0  # Default is 2.0

# For CAN: Verify IDs
from pyxcp.transport.can import Can
transport = Can(parent,
                can_interface="socketcan",
                can_channel="can0",
                can_id_master=0x700,  # Try scanning with xcp-id-scanner
                can_id_slave=0x701)

Related Issues: #188, #262, #179

Symptom: “Protection status error” or “Access denied”#

Cause: Resource (CAL/DAQ/STIM/PGM) is protected by seed/key.

Solution:

Check protection status:

xcp-info -t eth --config my_config.py --no-daq --no-pag

Add seed/key DLL to configuration:

# pyxcp_conf.py
def create_transport(parent):
    # ... transport config ...

SEED_KEY_DLL = "path/to/SeedNKeyXcp.dll"

For Windows 64-bit Python with 32-bit DLL:
- pyXCP automatically uses asamkeydll.exe bridge
- Ensure asamkeydll.exe is in pyxcp installation directory
- If missing, rebuild: gcc -m32 -o asamkeydll.exe asamkeydll.c

Related Issues: #200, #212

Import/Build Errors#

Symptom: “ModuleNotFoundError: No module named ‘pyxcp.transport.transport_ext’”#

Cause: C++ extensions not compiled or incompatible.

Solution by Platform:

Windows:

# Option 1: Install pre-built wheel (recommended)
pip install --upgrade pip
pip install pyxcp

# Option 2: Build from source (requires MSVC)
# Install Visual Studio Build Tools first
pip install pyxcp --no-binary pyxcp

Linux:

# Install build dependencies
sudo apt install build-essential cmake python3-dev pybind11-dev

# Reinstall
pip uninstall pyxcp
pip install pyxcp

macOS:

# Install Xcode Command Line Tools
xcode-select --install

# Install dependencies via Homebrew
brew install cmake pybind11

# Reinstall
pip install pyxcp

Manual Build:

git clone https://github.com/christoph2/pyxcp.git
cd pyxcp
python build_ext.py

# Verify extensions built
ls -la pyxcp/transport/transport_ext*.so  # Linux/macOS
dir pyxcp\transport\transport_ext*.pyd    # Windows

Related Issues: #240, #188, #199, #169

Symptom: “error: Microsoft Visual C++ 14.0 or greater is required”#

Cause: No C++ compiler on Windows.

Solution:

Use pre-built wheel (no compiler needed):

pip install --upgrade pip
pip install pyxcp

Or install Visual Studio Build Tools:
- Download: https://visualstudio.microsoft.com/downloads/
- Select: “Build Tools for Visual Studio 2022”
- Workload: “Desktop development with C++”
- Then: pip install pyxcp

Related Issues: #253, #262

Symptom: “UnboundLocalError: cannot access local variable ‘libdir’” (Linux)#

Cause: Python development libraries not found.

Solution:

# Install Python dev package
sudo apt install python3-dev libpython3-dev

# Verify Python library exists
find /usr -name "libpython*.so"
find /usr -name "libpython*.a"

# If missing, install specific version
sudo apt install python3.12-dev  # Replace with your Python version

# Then rebuild
pip install --no-binary pyxcp pyxcp

Note: pyXCP v0.26.3+ handles this gracefully by falling back to CMake auto-detection.

Related Issues: #169

Configuration Problems#

Symptom: “FileNotFoundError: Configuration file ‘pyxcp_conf.py’ does not exist”#

Cause: Config file not found when expected.

Solutions (pick one):

Use environment variable (v0.26.5+):

export PYXCP_CONFIG=/absolute/path/to/pyxcp_conf.py
python my_script.py

Pass logger explicitly (v0.26.4+):

import logging
from pyxcp.daq_stim import DaqToCsv

logger = logging.getLogger('my_daq')
logger.setLevel(logging.INFO)
daq_policy = DaqToCsv(daq_lists, logger=logger)

Create config file in one of search locations:
- Current working directory: ./pyxcp_conf.py
- Script directory: <script_dir>/pyxcp_conf.py
- User home: ~/.pyxcp/pyxcp_conf.py

Use programmatic config (v0.26.5+):

from pyxcp.config import create_application_from_config

config = {"Transport": {"CAN": {"device": "socketcan", "channel": "can0"}}}
app = create_application_from_config(config)

Config File Search Order:

PYXCP_CONFIG environment variable
--config command-line argument
./pyxcp_conf.py (current directory)
<script_dir>/pyxcp_conf.py
~/.pyxcp/pyxcp_conf.py

Related Issues: #260, #211

Symptom: PyInstaller/py2exe bundles fail with import errors#

Cause: PyInstaller doesn’t auto-detect native extensions.

Solution:

Create hook-pyxcp.py next to your script:

from PyInstaller.utils.hooks import collect_dynamic_libs

binaries = collect_dynamic_libs('pyxcp')
hiddenimports = [
    'pyxcp.transport.transport_ext',
    'pyxcp.cpp_ext.cpp_ext',
    'pyxcp.daq_stim.stim',
    'pyxcp.recorder.rekorder',
]

Build with:

pyinstaller --additional-hooks-dir=. your_script.py

Related Issues: #261, #203

DAQ Issues#

Symptom: DAQ recording produces no data or empty CSV#

Diagnostic Steps:

Check ECU DAQ support:

xcp-info -t eth --config my_config.py
# Look for "DAQ Info" section

Verify DAQ processor info:

with ap.run() as x:
    x.connect()
    if x.slaveProperties.supportsDaq:
        daq_info = x.getDaqInfo()
        print(f"Max DAQ: {daq_info['processor']['maxDaq']}")
        print(f"Max ODT: {daq_info['processor']['maxOdt']}")
    else:
        print("ERROR: ECU does not support DAQ!")

Check DAQ list configuration:

# Verify measurements have correct addresses
daq_lists = [
    DaqList(
        name="test",
        event_num=0,  # Event 0 usually exists
        measurements=[
            ("var1", 0x12345678, 0, "F32"),  # Check address!
        ]
    )
]

Enable debug logging:

import logging
logging.basicConfig(level=logging.DEBUG)
# Look for "DAQ" messages

Common Problems:

Wrong addresses: Use A2L file or xcp-info to verify
Wrong event: Event channel doesn’t exist or isn’t triggered
Protection: DAQ resource locked (see seed/key)
Max DAQ exceeded: Too many DAQ lists configured

Related Issues: #223, #226, #260

Symptom: “GET_DAQ_PROCESSOR_INFO failed” or hangs#

Cause: Some ECUs don’t implement this optional command or respond slowly.

Solution:

Skip with –no-daq flag:

xcp-info -t eth --config my_config.py --no-daq

In code, use try_command:

from pyxcp.types import TryCommandResult

status, daq_info = x.try_command(x.getDaqProcessorInfo)
if status == TryCommandResult.OK:
    # Use daq_info
else:
    # Fall back: manually configure DAQ

Increase timeout:

transport.timeout = 10.0  # Some ECUs are slow

Note: pyXCP v0.26.3+ handles missing GET_DAQ_PROCESSOR_INFO gracefully.

Related Issues: #247, #263

Symptom: DAQ timestamps are wrong or overflow#

Cause: Timestamp size mismatch or overflow not handled.

Solution:

Check timestamp size in DAQ configuration:

# If ECU uses 16-bit timestamps:
daq_list = DaqList(
    name="test",
    enable_timestamps=True,
    timestamp_size=2,  # 1, 2, or 4 bytes
    ...
)

Enable timestamp overflow handling (default in pyXCP):
- pyXCP automatically linearizes timestamps
- Both timestamp0 (host) and timestamp1 (ECU) are normalized to nanoseconds

Use PTP hardware timestamps (Linux Ethernet):

# In config file
c.Transport.Eth.ptp_timestamping = True

Related Issues: #219

CAN Problems#

Symptom: “No backend available” or CAN driver not found#

Diagnostic:

# Check available CAN drivers
pyxcp-probe-can-drivers

Solutions by Platform:

Linux (SocketCAN):

# Install can-utils
sudo apt install can-utils

# Bring up CAN interface
sudo ip link set can0 up type can bitrate 500000

# Verify
ip -details link show can0

Windows (Vector):

# Install python-can Vector backend
pip install python-can[vector]

# Verify Vector DLL exists
where vxlapi64.dll
# Should be in C:\Windows\System32 or Vector folder

Windows (PCAN):

# Install PCAN driver from PEAK website
# Install python-can PCAN backend
pip install python-can[pcan]

# Test with PCAN-View first

macOS:

Limited CAN support
Install vendor driver (PEAK, Kvaser)
Or use virtual CAN: can_interface="virtual"

Related Issues: #188, #227

Symptom: CAN bus errors (BUSOFF, ERROR_PASSIVE)#

Causes:

Wrong bitrate: CAN interface bitrate doesn’t match bus
Missing termination: 120Ω termination resistors not connected
Hardware issue: Bad cable, loose connector, defective adapter

Solution:

Verify bitrate matches:

# Linux: Check current bitrate
ip -details link show can0
# Should match ECU bitrate (typically 500000 or 1000000)

# Change if wrong
sudo ip link set can0 down
sudo ip link set can0 type can bitrate 500000
sudo ip link set can0 up

Check termination:
- CAN bus needs 120Ω resistor at each end
- Measure resistance: should be ~60Ω between CAN_H and CAN_L

Test with cansend/candump:

# Terminal 1
candump can0

# Terminal 2
cansend can0 123#DEADBEEF

# If this fails, hardware/bus issue, not pyXCP

Related Issues: #227

Symptom: Wrong CAN ID - ECU not responding#

Cause: can_id_master doesn’t match ECU’s expected ID.

Solution:

Scan for XCP slaves:

xcp-id-scanner -t can --config can_config.py
# Reports all responding IDs

Check A2L file (if available):
- Look for XCP_ON_CAN section
- CAN_ID_MASTER = ID ECU expects from tool
- CAN_ID_SLAVE = ID ECU uses for responses

Try common IDs:

# Common XCP CAN IDs
can_id_master = 0x700  # or 0x640, 0x300, 0x123
can_id_slave = 0x701   # usually master + 1

Enable CAN tracing:

# Linux: Capture CAN traffic while running pyXCP
candump can0 -L
# Look for XCP response frames (RES/ERR)

Related Issues: #188, #227

Performance Issues#

Symptom: DAQ recording is slow or drops samples#

Causes:

High CPU load: Python overhead at high frequencies
Disk I/O: Writing to slow storage
Network latency: Ethernet buffer too small

Solutions:

Use XMRAW format (faster than CSV):

from pyxcp.daq_stim import DaqRecorder
recorder = DaqRecorder(daq_lists, "measurement", 8)
# Convert to CSV later: xmraw-converter measurement.xmraw -o csv

Increase OS priority (Linux):

# Real-time scheduling
sudo chrt -f 50 python3 daq_script.py

# Or nice priority
sudo nice -n -10 python3 daq_script.py

Tune network buffers (Linux Ethernet):

sudo sysctl -w net.core.rmem_max=26214400
sudo sysctl -w net.core.wmem_max=26214400

Use C++ extensions (verify installed):

# Should work without error:
from pyxcp.transport import transport_ext
from pyxcp.daq_stim import stim

Reduce DAQ rate:
- Lower event frequency
- Record fewer variables
- Use decimation (record every Nth sample)

Related Issues: #219

Symptom: Slow connection establishment#

Causes:

Seed/key unlock slow: DLL taking time
Optional commands timing out: ECU doesn’t support them

Solutions:

Skip optional commands:

xcp-info --no-daq --no-pag --no-pgm --no-ids

Reduce timeout for optional commands:

from pyxcp.types import TryCommandResult

# Use try_command for optional features
status, result = x.try_command(x.getDaqProcessorInfo)
if status != TryCommandResult.OK:
    # Skip DAQ info

Pre-unlock before measurement:

# Unlock once at start
x.connect()
x.cond_unlock()  # Uses seed/key DLL
# ... then do multiple measurements without reconnecting

Related Issues: #247

Error Messages Reference#

Common XCP Error Codes#

When you see XcpError: <code> - <message>, refer to this table:

Code	Message	Meaning / Solution
0x00	CMD_SYNCH	Command mismatch. Disconnect and reconnect.
0x10	CMD_BUSY	ECU busy. Retry after delay or increase timeout.
0x20	DAQ_ACTIVE	DAQ already running. Stop DAQ first.
0x21	PGM_ACTIVE	Programming active. Wait for completion.
0x22	CMD_UNKNOWN	Command not supported. Check ECU capabilities.
0x23	CMD_SYNTAX	Wrong parameters. Check XCP spec.
0x30	OUT_OF_RANGE	Address/size invalid. Check A2L file.
0x31	WRITE_PROTECTED	Resource locked. Use seed/key unlock.
0x32	ACCESS_DENIED	Seed/key required. Configure SEED_KEY_DLL.
0x33	ACCESS_LOCKED	Session locked. Disconnect other tools.
0x34	PAGE_NOT_VALID	Calibration page not active. Check paging.
0x40	MODE_NOT_VALID	DAQ mode invalid. Check DAQ configuration.
0x41	SEGMENT_NOT_VALID	Memory segment doesn’t exist.
0x42	SEQUENCE_ERROR	Command sequence wrong. E.g., ALLOC_DAQ before FREE_DAQ.
0x43	DAQ_CONFIG	DAQ config error. Check event channels, ODT count.

Related: XCP specification ASAM MCD-1 XCP

Common Python Exceptions#

Exception	Common Causes & Solutions
`TimeoutError`	Connection timeout. See Connection Issues.
`XcpTimeoutError`	ECU not responding. Check timeout, network, ECU status.
`FileNotFoundError`	Config file missing. See Configuration Problems.
`ModuleNotFoundError`	Build issue. See Import/Build Errors.
`PermissionError`	USB/CAN access denied. See USB Permissions or run as sudo (not recommended).
`OSError: [Errno 48] Address already in use`	Port conflict (Ethernet). Kill other process or change port.
`OSError: [Errno 19] No such device`	CAN interface down. Run: `sudo ip link set can0 up type can bitrate 500000`
`ValueError: could not convert...`	Wrong data type in config. Check config syntax.

Platform-Specific Issues#

Linux:

Permissions: Add user to dialout and can groups
SocketCAN: Interface must be UP before use
USB: Create udev rules for non-root access

See: platform_setup → Linux Setup → USB Permissions

Windows:

MSVC required: For building from source (or use pre-built wheels)
DLL bridging: 32-bit seed/key DLLs need asamkeydll.exe
Firewall: Add Python to exceptions for Ethernet XCP

See: platform_setup → Windows Setup

macOS:

Xcode tools: Required for building
Limited CAN: Few native drivers; consider Linux VM

See: platform_setup → macOS Setup

USB Permissions#

Linux only - Required for USB XCP or USB-CAN adapters.

Symptom: PermissionError: [Errno 13] Permission denied

Solution: Create udev rule.

Find device IDs:

lsusb
# Look for your device, note idVendor:idProduct

Create udev rule: /etc/udev/rules.d/99-pyxcp-usb.rules

# Replace XXXX and YYYY with your vendor/product IDs
SUBSYSTEM=="usb", ATTRS{idVendor}=="XXXX", ATTRS{idProduct}=="YYYY", MODE="0666"

Reload rules:

sudo udevadm control --reload-rules
sudo udevadm trigger

Alternative: Add user to dialout group

sudo usermod -a -G dialout $USER
# Log out and back in

Getting Help#

If your issue isn’t covered here:

Search existing resources:
- FAQ - Specific Q&A
- quickstart - Getting started guide
- cli_tools - CLI tool documentation
- platform_setup - Platform-specific setup
- GitHub Issues - Known issues

Enable debug logging:

# Environment variable
export PYXCP_LOGLEVEL=DEBUG
python your_script.py

# Or programmatically
import logging
logging.basicConfig(level=logging.DEBUG)

Report an issue:

Include:
- pyXCP version: python -c "import pyxcp; print(pyxcp.__version__)"
- Python version: python --version
- Operating system: uname -a (Linux/macOS) or ver (Windows)
- Transport: CAN/Ethernet/USB/Serial
- Minimal reproducible code
- Full error traceback
- Debug log output
Ask in discussions:
- GitHub Discussions
- Provide context and what you’ve tried

Quick Diagnostic Checklist#

Run these commands to quickly diagnose your setup:

# 1. Verify pyXCP installed
python -c "import pyxcp; print(f'pyXCP {pyxcp.__version__} OK')"

# 2. Check C++ extensions
python -c "from pyxcp.transport import transport_ext; print('Extensions OK')"

# 3. Check CAN drivers
pyxcp-probe-can-drivers

# 4. Test network (Ethernet XCP)
ping <ECU_IP>

# 5. Test CAN interface (Linux)
ip link show can0
candump can0 &
cansend can0 123#DEADBEEF

# 6. Check config discovery
python -c "import os; print('PYXCP_CONFIG:', os.getenv('PYXCP_CONFIG', 'Not set'))"

# 7. Test simple connection
xcp-info -t eth --host <ECU_IP> --port 5555 --no-daq --no-pag

If all 7 succeed, your setup is correct. Issues are likely ECU-side or configuration.

Last updated: 2026-02-14 pyXCP version: 0.26.5+

Troubleshooting Guide#

Table of Contents#

Connection Issues#

Symptom: “Connection timeout” or “No response”#

Symptom: “Protection status error” or “Access denied”#

Import/Build Errors#

Symptom: “ModuleNotFoundError: No module named ‘pyxcp.transport.transport_ext’”#

Symptom: “error: Microsoft Visual C++ 14.0 or greater is required”#

Symptom: “UnboundLocalError: cannot access local variable ‘libdir’” (Linux)#

Configuration Problems#

Symptom: “FileNotFoundError: Configuration file ‘pyxcp_conf.py’ does not exist”#

Symptom: PyInstaller/py2exe bundles fail with import errors#

DAQ Issues#

Symptom: DAQ recording produces no data or empty CSV#

Symptom: “GET_DAQ_PROCESSOR_INFO failed” or hangs#

Symptom: DAQ timestamps are wrong or overflow#

CAN Problems#

Symptom: “No backend available” or CAN driver not found#

Symptom: CAN bus errors (BUSOFF, ERROR_PASSIVE)#

Symptom: Wrong CAN ID - ECU not responding#

Performance Issues#

Symptom: DAQ recording is slow or drops samples#

Symptom: Slow connection establishment#

Error Messages Reference#

Common XCP Error Codes#

Common Python Exceptions#

Platform-Specific Issues#

USB Permissions#

Getting Help#

Quick Diagnostic Checklist#

This Page