Troubleshooting

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 extensions are not loaded

Problem: python -c "import iso8583sim.core.parser as p; print(p._USE_CYTHON)" prints False. The PyPI wheels for Linux, macOS and Windows include the compiled extensions. On other platforms pip installs the pure-Python wheel (iso8583sim still works, only slower). Solutions:

Upgrade pip so it can pick a compiled wheel: pip install --upgrade pip, then reinstall iso8583sim.
To build from source, install a C compiler and reinstall with pip install --no-binary iso8583sim iso8583sim:
- 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:

Check the Cython extensions are loaded (see Cython extensions are not loaded).

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

Get started

Core

Card networks

Tools and interfaces

LLM features

Architecture

Operations

Installation Issues

”Module not found: iso8583sim”

Cython extensions are not loaded

LLM provider not available

LLM provider not configured

Parsing Issues

ParseError: Invalid bitmap

ParseError: Field length exceeds maximum

ParseError: Unknown field

Building Issues

BuildError: Validation failed

BuildError: Unknown field definition

Field padding incorrect

Validation Issues

PAN fails Luhn check

Missing required field

LLM Issues

LLMError: API rate limit

Generated message invalid

Performance Issues

Slow parsing

Memory usage high

Getting Help

​Installation Issues

​”Module not found: iso8583sim”

​Cython extensions are not loaded

​LLM provider not available

​LLM provider not configured

​Parsing Issues

​ParseError: Invalid bitmap

​ParseError: Field length exceeds maximum

​ParseError: Unknown field

​Building Issues

​BuildError: Validation failed

​BuildError: Unknown field definition

​Field padding incorrect

​Validation Issues

​PAN fails Luhn check

​Missing required field

​LLM Issues

​LLMError: API rate limit

​Generated message invalid

​Performance Issues

​Slow parsing

​Memory usage high

​Getting Help

Installation Issues

”Module not found: iso8583sim”

Cython extensions are not loaded

LLM provider not available

LLM provider not configured

Parsing Issues

ParseError: Invalid bitmap

ParseError: Field length exceeds maximum

ParseError: Unknown field

Building Issues

BuildError: Validation failed

BuildError: Unknown field definition

Field padding incorrect

Validation Issues

PAN fails Luhn check

Missing required field

LLM Issues

LLMError: API rate limit

Generated message invalid

Performance Issues

Slow parsing

Memory usage high

Getting Help