Troubleshooting¶

Common issues and solutions when using iso8583sim.

Installation Issues¶

"Module not found: iso8583sim"¶

Problem: Python cannot find the iso8583sim module.

Solutions:

Verify installation:
```
pip show iso8583sim
```

Check you're in the right virtual environment:

which python
pip list | grep iso8583sim

Reinstall:

pip uninstall iso8583sim
pip install iso8583sim

Cython compilation fails¶

Problem: python setup.py build_ext --inplace fails.

Solutions:

Ensure Cython is installed:
```
pip install cython>=3.0.0
```
Check you have a C compiler:
macOS: xcode-select --install
Linux: apt install build-essential
Windows: Install Visual Studio Build Tools
The library works without Cython - it falls back to pure Python automatically.

LLM provider not available¶

Problem: ProviderNotAvailableError: anthropic provider package is not installed

Solutions:

Install the provider:

pip install iso8583sim[anthropic]
# or
pip install anthropic>=0.40.0

Check what's installed:

from iso8583sim.llm import list_installed_providers
print(list_installed_providers())

LLM provider not configured¶

Problem: ProviderConfigError: Anthropic API key not found

Solutions:

Set the environment variable:
```
export ANTHROPIC_API_KEY="sk-ant-..."
```

Pass API key directly:

from iso8583sim.llm.providers.anthropic import AnthropicProvider
provider = AnthropicProvider(api_key="sk-ant-...")

Check what's configured:

from iso8583sim.llm import list_available_providers
print(list_available_providers())

Parsing Issues¶

ParseError: Invalid bitmap¶

Problem: ParseError: Invalid bitmap format

Causes: - Bitmap is not exactly 16 hex characters - Contains non-hex characters - Message is truncated

Solution:

# Bitmap must be exactly 16 hex characters (8 bytes)
# Example valid bitmap: "7024058020C09000"

# Check your message structure:
message = "0100702406C120E09000..."
#          ^^^^                   = MTI (4 chars)
#              ^^^^^^^^^^^^^^^^   = Bitmap (16 chars)
#                              ^^ = Field data starts here

ParseError: Field length exceeds maximum¶

Problem: A field value is longer than allowed.

Solution:

# Check field definition
from iso8583sim.core.types import get_field_definition

field_def = get_field_definition(2)
print(f"Field 2 max length: {field_def.max_length}")

# For LLVAR fields, check the length prefix
# "164111111111111111" = 16 chars, value is 16 chars
# "204111111111111111" = 20 chars, but value is only 18 chars - MISMATCH

ParseError: Unknown field¶

Problem: Parsing fails on a network-specific field.

Solution:

# Specify the network when parsing
from iso8583sim.core.types import CardNetwork

parser = ISO8583Parser()
message = parser.parse(raw, network=CardNetwork.VISA)

Building Issues¶

BuildError: Validation failed¶

Problem: Message doesn't pass validation during build.

Solution:

# Check what's wrong before building
from iso8583sim.core.validator import ISO8583Validator

validator = ISO8583Validator()
errors = validator.validate_message(message)
for error in errors:
    print(error)

# Fix the issues, then build

BuildError: Unknown field definition¶

Problem: Building fails because field isn't recognized.

Solution:

# Check field exists
from iso8583sim.core.types import ISO8583_FIELDS

if field_number not in ISO8583_FIELDS:
    print(f"Field {field_number} is not a standard ISO 8583 field")

# For network-specific fields, set the network
message.network = CardNetwork.VISA

Field padding incorrect¶

Problem: Field values aren't padded correctly.

Solution:

# The builder handles padding automatically
# But you can check field definitions:

from iso8583sim.core.types import get_field_definition

field_def = get_field_definition(4)  # Amount
print(f"Type: {field_def.field_type}")
print(f"Length: {field_def.max_length}")
print(f"Padding: {field_def.padding_char} ({field_def.padding_direction})")

# Field 4 (Amount): 12 digits, left-padded with zeros
# "1000" becomes "000000001000"

Validation Issues¶

PAN fails Luhn check¶

Problem: Field 2 (PAN) failed Luhn check

Solution:

# Use a valid test PAN
# These are valid Luhn-check PANs for testing:
VALID_TEST_PANS = {
    "VISA": "4111111111111111",
    "Mastercard": "5500000000000004",
    "AMEX": "378282246310005",
    "Discover": "6011111111111117",
}

Missing required field¶

Problem: Missing required field: 22

Solution:

# Different networks require different fields
# Check requirements for your network:

from iso8583sim.core.validator import ISO8583Validator

validator = ISO8583Validator()
required = validator.network_required_fields.get(CardNetwork.VISA, [])
print(f"VISA requires: {required}")

# Add missing fields to your message
message.fields[22] = "051"  # POS Entry Mode

LLM Issues¶

LLMError: API rate limit¶

Problem: LLMError: Rate limit exceeded

Solution:

import time

# Add delay between requests
for message in messages:
    try:
        explanation = explainer.explain(message)
    except LLMError:
        time.sleep(1)  # Wait and retry
        explanation = explainer.explain(message)

Generated message invalid¶

Problem: LLM generates an invalid message.

Solution:

# Always validate generated messages
message = generator.generate(description, validate=False)

# Then validate manually
errors = validator.validate_message(message)
if errors:
    print("LLM generated invalid message:")
    for error in errors:
        print(f"  - {error}")

Performance Issues¶

Slow parsing¶

Problem: Parsing is slower than expected.

Solutions:

Install Cython extensions:

pip install iso8583sim[perf]
python setup.py build_ext --inplace

Reuse parser instances:

# Good
parser = ISO8583Parser()
for msg in messages:
    result = parser.parse(msg)

# Bad
for msg in messages:
    result = ISO8583Parser().parse(msg)

Disable debug logging:

import logging
logging.getLogger('iso8583sim').setLevel(logging.WARNING)

Memory usage high¶

Problem: Memory grows with message volume.

Solution:

# Use object pooling
from iso8583sim.core.pool import MessagePool

pool = MessagePool(size=1000)
parser = ISO8583Parser(pool=pool)

for raw in messages:
    msg = parser.parse(raw)
    process(msg)
    pool.release(msg)  # Return to pool

Getting Help¶

If you can't resolve an issue:

Check the API Reference for correct usage
Search GitHub Issues
Open a new issue with:
Python version (python --version)
iso8583sim version (pip show iso8583sim)
Minimal code to reproduce
Full error traceback