Troubleshooting

Common issues and solutions for WAX SDK

Find solutions to common problems when working with WAX.

Installation issues

Python version mismatch

Problem: WAX requires Python 3.12 or higher, but you have an older version.

Solution: Upgrade Python:

# Check current version
python3 --version

# Ubuntu/Debian
sudo apt update
sudo apt install python3.12

# macOS
brew install python@3.12

Then create a new virtual environment:

python3.12 -m venv venv
source venv/bin/activate
pip install hiveio-wax

Poetry not found

Problem: poetry command not found.

Solution: Install Poetry and add to PATH:

# Install Poetry 2.1.3
curl -sSL https://install.python-poetry.org | python3 - --version 2.1.3

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

# Verify installation
poetry --version

Protobuf compiler not found

Problem: Build fails with “protoc not found” or similar error.

Solution: Install the protobuf compiler:

# Ubuntu/Debian
sudo apt install protobuf-compiler

# macOS
brew install protobuf

# Verify installation
protoc --version

Wheel not compatible

Problem: ERROR: hiveio_wax-*.whl is not a supported wheel on this platform.

Solution: The wheel doesn’t match your Python version or platform. Check:

# Check your Python version and platform
python3 -c "import sys; print(f'Python {sys.version_info.major}.{sys.version_info.minor}'); print(f'Platform: {sys.platform}')"

# Install the correct wheel or build from source
export PYTHON_VERSION=3.12
./python/wax/scripts/build_wax.sh

pnpm command not found

Problem: pnpm is not installed for TypeScript development.

Solution: Install pnpm:

# Using npm
npm install -g pnpm

# Using standalone script
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Verify installation
pnpm --version

Build issues

Missing Boost libraries

Problem: Build fails with missing Boost library errors.

Solution: Use the official CI base image which includes pre-compiled Boost:

# Pull the CI base image
docker pull registry.gitlab.syncad.com/hive/wax/ci-base-image:pypa_2_28-13

# Or build inside the image
docker run --rm -v "${PWD}:${PWD}" -w "${PWD}" \
  registry.gitlab.syncad.com/hive/wax/ci-base-image:pypa_2_28-13 \
  bash -c "./python/wax/scripts/build_wax.sh 1"

Submodule not initialized

Problem: Build fails because the hive submodule is not initialized.

Solution: Initialize and update submodules:

git submodule update --init --recursive

# Verify submodule is initialized
ls hive/libraries/protocol/proto/

WASM build fails

Problem: TypeScript WASM build fails with compilation errors.

Solution: Ensure all dependencies are installed and submodules are initialized:

# Check submodules
git submodule update --init --recursive

# Clean and rebuild
cd ts
rm -rf node_modules dist build_wasm
pnpm install
pnpm run build

# Check build logs
cat wasm/build_wasm/*.log

Out of memory during build

Problem: Build process crashes with out of memory errors.

Solution: Increase available memory or reduce parallel jobs:

# Reduce pytest parallel jobs
poetry run pytest -n 2  # Instead of -n auto

# For Docker builds, increase memory limit
docker run --memory=8g ...

Runtime issues

Import error: cannot import name

Problem: ImportError: cannot import name 'create_wax_foundation' from 'wax'

Solution: Ensure WAX is properly installed:

# Verify installation
python3 -c "import wax; print(wax.__version__)"

# Reinstall if needed
pip uninstall hiveio-wax
pip install hiveio-wax

# Or install from wheel
pip install --force-reinstall ./dist/hiveio_wax-*.whl

Module not found: @hiveio/wax

Problem: TypeScript cannot find the WAX module.

Solution: Ensure the package is installed:

# Verify installation
npm list @hiveio/wax

# Install if missing
npm install @hiveio/wax

# Or install from tarball
npm install ./ts/wasm/dist/*.tgz

Protobuf deserialization errors

Problem: Errors when deserializing protocol buffer messages.

Solution: Ensure protobuf versions match:

# Python: Check protobuf version
pip show protobuf

# Should be ^6.33.0 - upgrade if needed
pip install --upgrade 'protobuf>=6.33.0,<7'

# Regenerate proto files
./python/wax/scripts/compile_proto.sh

API connection failures

Problem: Cannot connect to Hive API nodes.

Solution: Check your endpoint and network:

# Python
from wax import create_hive_chain

# Try different endpoints
endpoints = [
    "https://api.hive.blog",
    "https://api.deathwing.me",
    "https://api.openhive.network"
]

for endpoint in endpoints:
    try:
        chain = create_hive_chain(endpoint)
        info = chain.api.get_dynamic_global_properties()
        print(f"Connected to {endpoint}")
        break
    except Exception as e:
        print(f"Failed to connect to {endpoint}: {e}")

Transaction signing failures

Problem: Transactions fail to sign or broadcast.

Solution: Verify your signing setup:

# Python example
from wax import create_wax_foundation

# Create foundation
wax = create_wax_foundation()

# Verify transaction structure
tx = wax.create_transaction()
tx.push_operation({...})

# Check transaction before signing
print(tx.json)

# Ensure signer is properly configured
# For beekeeper: check wallet is unlocked
# For keychain: check browser extension is installed

Testing issues

Mock server won't start

Problem: Tests fail because mock server cannot start.

Solution: Check if port is already in use:

# Check if port 4000 is in use
lsof -i :4000

# Kill existing process
kill -9 <PID>

# Or use a different port
export MOCK_SERVER_PORT=4001
./python/tests/wax/run_tests.sh

Playwright browsers not installed

Problem: TypeScript tests fail with “Browser not found” error.

Solution: Install Playwright browsers:

cd ts
pnpm exec playwright install

# Or install specific browser
pnpm exec playwright install chromium

Import errors in tests

Problem: Tests fail with import errors.

Solution: Set PYTHONPATH correctly:

# Set PYTHONPATH to include python directory
export PYTHONPATH="${PWD}/python:${PYTHONPATH}"

# Or use the test script which sets it automatically
./python/tests/wax/run_tests.sh

Tests timeout

Problem: Tests hang or timeout.

Solution: Increase timeout or debug hanging tests:

# Increase mock server timeout
export TIMEOUT_PROXY_MOCK_SERVER_SECONDS=60
./python/tests/wax/run_tests.sh

# Run tests with verbose output
poetry run pytest -vvv --log-cli-level=DEBUG

# Run single test to isolate issue
poetry run pytest -vvv path/to/test_file.py::test_function

Development issues

Linter errors

Problem: Linter fails with style violations.

Solution: Auto-fix issues where possible:

# Python: Auto-fix with Ruff
poetry run ruff check --fix .

# TypeScript: Auto-fix with ESLint
cd ts
pnpm run lint --fix

Type checking errors

Problem: MyPy or TypeScript type checking fails.

Solution: Review type errors and fix:

# Python: Run MyPy with detailed output
poetry run mypy . --show-error-codes --pretty

# TypeScript: Run tsc with detailed output
cd ts
npx tsc --noEmit --pretty

Git hooks fail

Problem: Pre-commit hooks fail on commit.

Solution: Run pre-commit manually and fix issues:

# Install pre-commit hooks
pre-commit install

# Run all hooks
pre-commit run --all-files

# Skip hooks temporarily (not recommended)
git commit --no-verify

CI pipeline failures

Problem: GitLab CI pipeline fails.

Solution: Check pipeline logs and run locally:

# Run tests locally before pushing
./python/tests/wax/run_tests.sh
cd ts && pnpm run test

# Check linters
poetry run ruff check .
poetry run mypy .
cd ts && pnpm run lint

# Check pipeline configuration
gitlab-ci-local --list

Performance issues

Slow imports

Problem: Importing WAX takes a long time.

Solution: This is expected for first import as native modules are loaded. Subsequent imports are cached:

# Python: Import at module level, not in functions
import wax

# Not recommended - imports inside loop
def process_items(items):
    for item in items:
        from wax import create_wax_foundation  # Slow!
        ...

# Recommended - import once
from wax import create_wax_foundation

def process_items(items):
    wax = create_wax_foundation()
    for item in items:
        ...

Large memory usage

Problem: WAX uses more memory than expected.

Solution: Optimize memory usage:

# Python: Use context managers
from wax import create_hive_chain

# Release resources when done
def process_transactions():
    chain = create_hive_chain("https://api.hive.blog")
    # ... process transactions ...
    del chain  # Explicit cleanup

# TypeScript: Use memory profiling
// See examples/ts/memory-used/ for profiling tools

Slow transaction building

Problem: Building transactions is slow.

Solution: Batch operations and reuse objects:

# Slow - creating new foundation each time
for op in operations:
    wax = create_wax_foundation()
    tx = wax.create_transaction()
    tx.push_operation(op)

# Fast - reuse foundation
wax = create_wax_foundation()
for op in operations:
    tx = wax.create_transaction()
    tx.push_operation(op)

Getting help

If you can’t find a solution to your problem:

GitLab issues

Report bugs or request features

Discussions

Ask questions and get help

Stack Overflow

Search existing questions

Documentation

Browse the full documentation

Reporting bugs

When reporting a bug, include:

1. Version information:

   # Python
   python3 --version
   pip show hiveio-wax
   
   # TypeScript
   node --version
   npm list @hiveio/wax
   

2. Environment details:

   • Operating system and version
   • Python/Node.js version
   • Installation method (pip, npm, from source)

3. Minimal reproduction:

   • Simplest code that reproduces the issue
   • Steps to reproduce
   • Expected vs actual behavior

4. Error messages:

   • Full error traceback
   • Relevant log output
   • Console errors (for browser issues)

Next steps

Contributing

Help improve WAX

Building from source

Build WAX locally