Troubleshooting

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:

Version information:

# Python
python3 --version
pip show hiveio-wax

# TypeScript
node --version
npm list @hiveio/wax

Environment details:
- Operating system and version
- Python/Node.js version
- Installation method (pip, npm, from source)
Minimal reproduction:
- Simplest code that reproduces the issue
- Steps to reproduce
- Expected vs actual behavior
Error messages:
- Full error traceback
- Relevant log output
- Console errors (for browser issues)

Additional Resources

Troubleshooting

Installation issues

Build issues

Runtime issues

Testing issues

Development issues

Performance issues

Getting help

GitLab issues

Discussions

Stack Overflow

Documentation

Reporting bugs

Next steps

Contributing

Building from source

Build docs developers (and LLMs) love

Additional Resources

Documentation Index

​Installation issues

​Build issues

​Runtime issues

​Testing issues

​Development issues

​Performance issues

​Getting help

GitLab issues

Discussions

Stack Overflow

Documentation

​Reporting bugs

​Next steps

Contributing

Building from source

Build docs developers (and LLMs) love

Installation issues

Build issues

Runtime issues

Testing issues

Development issues

Performance issues

Getting help

Reporting bugs

Next steps