🔧 Troubleshooting¶

Common Issues¶

Installation Problems¶

"No module named 'b_fast'"¶

# Make sure you installed the package
pip install bfast-py

# Or with uv
uv add bfast-py

Compilation Errors¶

# Update pip and try again
pip install --upgrade pip setuptools wheel
pip install bfast-py --force-reinstall

Performance Issues¶

Slower than Expected¶

1. Check data structure: B-FAST excels with Pydantic objects and NumPy arrays
2. Enable compression: Use compress=True for large payloads
3. Batch processing: Process lists of similar objects for best performance

Memory Usage¶

# Reuse encoder instance
encoder = b_fast.BFast()
for batch in data_batches:
    result = encoder.encode_packed(batch, compress=True)

Compatibility Issues¶

Unsupported Data Types¶

B-FAST currently supports: - ✅ Basic Python types (int, str, bool, float, bytes, None) - ✅ Collections (list, tuple, set, dict) - ✅ Pydantic models (v1 and v2) - ✅ datetime, date, and time (via ISO 8601 type preservation) - ✅ UUID and Decimal - ✅ DataFrames & Series: Polars, Pandas, and PyArrow tables - ✅ NumPy arrays (float64, etc.) - ❌ Arbitrary custom classes without dict or attribute access - ❌ Complex numbers (complex)

TypeScript Client Issues¶

// Make sure to handle binary data correctly
const response = await fetch('/api/data');
const buffer = await response.arrayBuffer();
const data = BFastDecoder.decode(buffer);

Performance Optimization¶

When B-FAST is Optimal¶

• Network bandwidth is limited (mobile, IoT)
• Large datasets with repeated structure (lists of Pydantic objects)
• NumPy arrays (148x speedup vs JSON)
• Storage efficiency matters (79% size reduction)

When to Consider Alternatives¶

• Ultra-fast networks (10+ Gbps internal)
• Simple data structures (single values, small objects)
• CPU-constrained environments

Optimization Tips¶

# 1. Use compression for large payloads
result = encoder.encode_packed(data, compress=True)

# 2. Batch similar objects together
users = [User(...) for _ in range(1000)]  # Good
mixed = [user1, "string", 123, dict()]    # Less optimal

# 3. Reuse encoder instances
encoder = b_fast.BFast()  # Create once
for batch in batches:
    encoder.encode_packed(batch)  # Reuse

Getting Help¶

Debug Information¶

import b_fast
print(f"B-FAST version: {b_fast.__version__}")

# Test basic functionality
encoder = b_fast.BFast()
test_data = {"test": 123}
result = encoder.encode_packed(test_data, False)
print(f"Encoded {len(result)} bytes")

Reporting Issues¶

When reporting issues, please include: 1. Python version and operating system 2. B-FAST version (pip show bfast-py) 3. Sample data structure that causes the issue 4. Error message (full traceback) 5. Expected vs actual behavior

Community Support¶

• GitHub Issues: Report bugs and feature requests
• Discussions: Ask questions and share use cases
• Documentation: Complete documentation

FAQ¶

Q: Why is B-FAST slower than orjson for simple data?¶

A: B-FAST is optimized for bandwidth-constrained scenarios and complex data structures. For simple data on fast networks, orjson may be faster.

Q: Can I use B-FAST with Django or Django Ninja?¶

A: Yes! B-FAST includes native integrations: BFastRenderer for Django Ninja and BFastHttpResponse / BFastStreamingHttpResponse for standard Django.

Q: How do I decode B-FAST payloads in Python?¶

A: Use encoder.decode_packed(binary_data) to deserialize payloads back into Python native structures.

Q: How does compression work?¶

A: B-FAST includes built-in LZ4 compression. Pass compress=True to significantly reduce network payload sizes without external dependencies.