Troubleshooting

Common issues and solutions when running BLVM nodes. See Node Operations for operational details.

Symptom guide

Start from what you observe: each row links to a section on this page.

Mainnet IBD

First-time sync setup: First Node Setup: Mainnet initial sync.

Node Won't Start

Port Already in Use

Error: Address already in use or Port 8332 already in use

Solution:

# Use a different JSON-RPC bind (full host:port)
blvm --rpc-addr 127.0.0.1:8334

# Or pick a different P2P listen address
blvm --listen-addr 0.0.0.0:8334

# Or find and stop the process using the port
lsof -i :8332
kill <PID>

Permission Denied

Error: Permission denied when accessing data directory

Solution:

# Fix directory permissions
sudo chown -R $USER:$USER /var/lib/blvm

# Or use a user-writable directory
blvm --data-dir ~/.blvm

Storage Issues

Bitcoin Core drop-in migration

See Starting from a Bitcoin Core datadir.

Database Backend Fails

Error: Failed to initialize database backend

Solution:

• The system automatically falls back to alternative backends when the chosen one fails
• Check data directory permissions and sufficient disk space
• Set backend explicitly in config if needed: [storage] database_backend = "rocksdb" / "heed3" / "redb" / "sled" / "tidesdb", or keep "auto" (default builds usually pick heed3 first). See Configuration Reference.

Corrupted Database

Error: Database corruption or inconsistent state

Solution:

1. Stop the node before deleting anything.
2. Identify the active backend under {data_dir}: e.g. heed3/, rocksdb/, redb/, sled/, tidesdb/ (see Storage backends).
3. Back up the datadir, then remove only the corrupted backend subtree (not generic data/blocks / data/chainstate Core paths unless you intentionally reset a Core-import layout).
4. Restart; expect resync or migration depending on what you removed.

For Core chainstate import errors (LevelDB .ldb vs RocksDB layout, mixed .ldb + .sst index), see Storage backends: Core LevelDB interop and use blvm config convert-core / migration tooling rather than blind rm -rf.

Network Issues

No Peer Connections

Symptoms: Node starts but shows 0 connections

Solutions:

• Check firewall settings (port 8333 for mainnet, 18333 for testnet)
• Verify network connectivity
• Try adding manual peers: persistent_peers in blvm.toml, or the addnode RPC method after the node is up
• Check DNS seed resolution

Connection Drops

Symptoms: Connections established but immediately drop

Solutions:

• Check network stability
• Verify protocol version compatibility
• Review node logs for specific error messages
• Adjust transport in blvm.toml (transport_preference = "tcponly", etc.) or set BLVM_NODE_TRANSPORT (e.g. tcp_only): there is no --transport flag on blvm

RPC Issues

RPC Connection Refused

Error: Connection refused when calling RPC

Solutions:

• Verify the process is listening on --rpc-addr (mainnet default 127.0.0.1:8332; testnet 127.0.0.1:18332; regtest 127.0.0.1:18443 when using blvm without overrides)
• Check bind address: use 0.0.0.0:8332 when exposing RPC in a container
• Check firewall for the RPC port you configured

RPC Authentication Errors

Error: Unauthorized or authentication failures

Solutions:

• Configure [rpc_auth] tokens (or RPC_AUTH_TOKENS / token_file) when required = true
• Send Authorization: Bearer <token> on HTTP JSON-RPC requests
• For admin-only methods (generatetoaddress, getblocktemplate, submitblock, loadmodule, …), use a token listed in admin_tokens or HTTP Basic password: otherwise HTTP 403 (not JSON-RPC -32603). See JSON-RPC error reference
• For local development only, leave [rpc_auth].required = false (not for production)

savemempool / mempool.dat errors

Error: savemempool fails with I/O or “no such file or directory” for the data directory

Cause: Earlier builds wrote mempool.dat only when the data directory already existed.

Solutions:

• Use a current build: savemempool creates the data directory (parent of mempool.dat) before writing
• Ensure --data-dir / DATA_DIR points to the intended location
• Check disk space and permissions on the data directory path

Module System Issues

Module Not Loading

Error: Module fails to load or start

Solutions:

• Verify module.toml exists and is valid (manifest name matches [modules] pin and [modules.<name>] table keys)
• Check module binary exists at the path expected by module.toml entry_point under [modules].modules_dir
• Review node stdout / RUST_LOG (module subprocess output is forwarded over IPC; there is no fixed data/modules/logs/ tree in core)
• Inspect module state under {modules.data_dir}/<manifest-name>/ (default {modules.data_dir} is data/modules relative to the process unless configured)
• Verify module capabilities in module.toml match what the module requests at runtime
• Ensure [modules].socket_dir exists and is writable (default data/modules/sockets)

IPC Connection Failures

Error: Module cannot connect to node IPC

Solutions:

• Ensure [modules].socket_dir exists (default data/modules/sockets under the node working directory unless overridden in blvm.toml)
• Check file permissions on the socket directory
• Verify the module process can access Unix domain sockets on the host
• Restart the node to recreate IPC sockets after crashes

Performance Issues

Slow Initial Sync

Symptoms: Node takes very long to sync

Solutions:

• Tune [storage.pruning] in blvm.toml (see Storage backends); pruning is not toggled via ad-hoc blvm --pruning … flags
• Increase cache sizes in config
• Use a storage backend suited to your workload (see Storage Backends)
• Check network bandwidth and latency

High Memory Usage

Symptoms: Node uses excessive memory

Solutions:

• Reduce cache sizes in config
• Enable pruning to reduce data size
• Check for memory leaks in logs
• Consider using lighter storage backend

Getting Help

• Check node logs: console output from blvm --verbose, or RUST_LOG / [logging] filter in config
• Review Configuration for options
• See RPC API for available methods
• Check GitHub issues for known problems

See Also

• Node Operations - Node management and operations
• Node Configuration - Configuration options
• Getting Started - First node setup
• FAQ - Frequently asked questions
• Starting from a Bitcoin Core datadir - Import a synced Core datadir
• Upgrading an existing deployment - Version upgrades