Skip to main content
Version: v5.0.0

Troubleshooting

Troubleshooting HOPR node issues​

How to check if my node is working correctly?​

Every HOPRd node comes with the Node API Swagger UI, a web page where you can send requests to your node and see its answers.

  1. Open the Swagger UI

    In your browser, go to:

    http://<NODE_IP>:<API_PORT>/swagger-ui/
    • <NODE_IP>: the IP address of the machine your node runs on. If the node runs on the same computer as your browser, use localhost.
    • <API_PORT>: your node's API port. The default is 3001.
      • Docker: the first port in -p 3001:3001 in your Docker command.
      • Docker Compose: HOPRD_API_PORT in your .env file.

    Example: http://192.168.1.50:3001/swagger-ui/

    note

    If the page doesn't load, make sure your node is running and that your server's firewall allows connections to the API port from your computer.

  2. Authorize with your API token

    1. Click Authorize at the top right of the page.
    2. In the api_token (apiKey) field, enter your API token and click Authorize, then Close.

    Your API token is:

    • Docker: api.auth in ~/hoprd/hoprd-docker.cfg.yaml.
    • Docker Compose: HOPRD_API_TOKEN in your .env-secrets file.

  3. Run a request

    Click a request to expand it, click Try it out, then click Execute. The answer appears under Response body.

    If you get a 401 response, your API token is wrong. Repeat step 2.

  4. Check the results

    Run these requests and compare the results:

    SectionRequestFieldExpected value
    NodeGET …/node/statusoverallReady. If it shows Initializing, your node is still syncing. Wait a few minutes and run it again.
    NodeGET …/node/version(response)The latest version on the Releases page.
    NodeGET …/node/infohoprNodeSafeYour Safe address. If you migrated, your new Safe. If it shows your old Safe, your node uses the wrong hopr.safe_module.safe_address.
    NodeGET …/node/infochainStatusReady
    NodeGET …/node/infoconnectivityStatusGreen or Yellow. Orange means only minimal connectivity, Red means not connected.
    NodeGET …/node/infoannouncedAddressYour public IP and P2P port, for example /ip4/1.2.3.4/tcp/9091.
    AccountGET …/account/addressesnativeYour node address. If you migrated, the same address you had on v3.0.x. If it's different, your node didn't load your backed-up identity file.
    AccountGET …/account/balancesnativeAt least 0.01 xDai
    AccountGET …/account/balancessafeHoprThe wxHOPR in your Safe. If you migrated, the wxHOPR you moved to your new Safe.
    AccountGET …/account/balancessafeHoprAllowanceMore than 0 wxHOPR.

  5. Check that your node appears in the network dashboard

    Go to the HOPR Network Dashboard and enter your node address in Search Node. Use the native value from GET …/account/addresses in step 4. Your node should be listed, with Last Seen showing Online. If it isn't listed yet, wait a few minutes and search again.

If all values match and your node appears in the dashboard, your node is working correctly.

How can I verify if Cover Traffic is being relayed through my node(s) and if I'm receiving rewards?​

On the Piz Palu network, Cover Traffic doesn't depend on your stake. Five Cover Traffic nodes send short bursts of traffic through every eligible node, so each eligible node gets a burst about once every 20 minutes. Your node earns a ticket for every packet it relays, the same as for any other traffic. There is no APR and no fixed daily reward. For background, see Cover Traffic on HOPR Piz Palü.

The Cover Traffic nodes on Piz Palu are:

0x51624c828c175cc81d6a7dd22a9a30d68c6a1ae0
0xa64109ed980c902ac554662b9d569a6a3f71e7a7
0x02d7d9ca7788e674676f809ac984cbf59e4b6099
0x50eac8e328847e5389aabb267398386db7225644
0x991a376c646274d74adb3b25ccc292a775f352f1
note

The eligibility and burst settings below are the first values used on Piz Palu. They may change as the network grows.

  1. Check that your node is running

    Follow How to check if my node is working correctly?. Your node must appear in the network dashboard and show Online, because a Cover Traffic node skips nodes it can't reach.

  2. Check that your node is eligible

    Your node is eligible when it has at least 5 open outgoing payment channels, each with at least 100 wxHOPR. Your stake, your Safe balance and your location don't count.

    In the Swagger UI, run GET …/channels and look at the outgoing list. Count the channels with status Open and a balance of 100 wxHOPR or more.

    Keep at least 150 wxHOPR in each channel. When your node relays traffic, it pays the next node from its channel, so the balance drops over time and could fall below 100 wxHOPR. The default channel strategy doesn't fund your channels this high. To have your node keep them at about 150 wxHOPR, change your funding values as described in Fund your channels for Cover Traffic.

  3. Check that your node relays traffic and earns tickets

    In the HOPR Network Dashboard, search for your node address. Last measured throughput and Throughput 24h avg. show the Cover Traffic your node relayed.

    Then, in the Swagger UI, run GET …/tickets/statistics:

    FieldExpected value
    winningCountGoes up over time. Check again after an hour: your node gets a burst about every 20 minutes.
    unredeemedValueCan stay low, because your node redeems winning tickets as they arrive.
    neglectedValue0 wxHOPR
    rejectedValue0 wxHOPR

    Whether a ticket wins depends on the ticket winning probability, and its value depends on the ticket price. Both are still being tuned, so the number of winning tickets per burst can change.

  4. Make sure your node can handle bursts

    A burst lasts about 10 seconds at 30 Mbit/s, and bursts from different Cover Traffic nodes can arrive at the same time. A node that can't keep up drops packets and loses the tickets for them, and other nodes may close their channels to it.

    The minimum for a relay node is 4 CPU cores, 4 GB of RAM and 5 GB of disk, with an uplink that handles 10 Mbit/s in both directions. Give your node some headroom above this, especially on a VPS.

Cover Traffic is only part of your earnings

A node that is eligible for Cover Traffic also relays real traffic, for example from Gnosis VPN, and earns tickets for it in the same way.

How to retrieve logs from your node?​

  1. Find your container ID

    Connect to your machine and execute the command docker ps. This will provide you with a list of Docker containers you are currently running. Among them, locate the container with the label europe-west3-docker.pkg.dev/hoprassociation/docker-images/hoprd:stable and note the container ID.

  2. Get the logs

    Get the logs from the docker container using the following command: docker logs -t <Your_Container_ID> >> <File_name.log>. Replace <Your_Container_ID> with your docker container ID. Replace <File_name.log> with your container ID and <File_name.log> with your chosen file name. After executing the command, wait until it finishes writing the logs to the file.

    Example:

    docker logs -t 4951b2990936 >> logs_from_hopr_node.log

Troubleshooting Blokli issues​

These answers apply if you run Blokli locally. Run all commands from the docker folder of the Blokli repository.

Why does Blokli keep restarting?​

If docker compose ps shows bloklid as Restarting (1), Blokli exits at startup.

  1. Find the error

    docker compose logs bloklid --tail 50

  2. Fix the error

    Find the error in the logs and fix it:

    • TOML parse error at line N: there's a typo in config-docker.toml, for example a stray ". Fix the line shown, then run docker compose restart bloklid.
    • RPC does not support debug_traceTransaction: the tracing check is on and your RPC has no debug API. Set enable_revert_reason_tracing = false under [api.transactions], or use an RPC with the debug API. Then run docker compose restart bloklid.
    • Unknown network 'piz-palu-prod': your Blokli image is too old. Pull or build a newer bloklid:latest image as described in step 3 of Set up Blokli, then run docker compose up -d --force-recreate bloklid.
    • PostgreSQL exits with Error: in 18+ …: the PostgreSQL volume path is outdated. Fix it as described in step 4 of Set up Blokli, then run docker compose down -v and docker compose up -d.

Why can't I connect to Blokli's API?​

  1. Check the error

    • curl: (7) Failed to connect … Connection refused: bloklid isn't running, keeps restarting, or its port isn't published. Run docker compose ps -a and check that bloklid is Up with 0.0.0.0:8080->8080/tcp. If it keeps restarting, see Why does Blokli keep restarting?
    • connection reset or empty reply: the API listens on 127.0.0.1 inside the container. Set bind_address = "0.0.0.0:8080" under [api] in config-docker.toml, then run docker compose restart bloklid.

  2. Check the connection from your node

    If Blokli responds on its own machine but your node can't reach it, check that you use the right Blokli URL for your setup, as described in Connect your node to Blokli. If your node runs on another machine, allow port 8080 in the firewall of the Blokli machine.

Why doesn't my Blokli configuration change take effect?​

The container wasn't restarted, or you edited another file.

  1. Recreate the container

    docker compose up -d --force-recreate bloklid

  2. Check the loaded configuration

    Run docker compose logs bloklid --tail 50. The configuration Blokli loaded is printed at the top of the logs. Check that it shows your change.

Why does Blokli show RPC errors?​

Errors such as 429 or timeouts mean that your RPC endpoint limits your requests.

  1. Limit the requests or change the RPC endpoint

    In config-docker.toml, set max_rpc_requests_per_sec = 20 or lower. Or use a faster RPC endpoint in rpc_url, as described in the Custom RPC provider guide.

  2. Restart Blokli

    docker compose restart bloklid

Why isn't Blokli ready yet?​

Blokli is ready only after its first sync. Until then:

  • /readyz reports "status":"not_ready", with "last_indexed_block":0 and a very large lag. Blokli sets last_indexed_block only after both historical phases finish.
  • GraphQL queries return GraphQL API is not ready yet. Indexer is still catching up.

Both are expected. Follow the sync progress with the metrics and wait until /readyz reports ready, as described in Wait for the first sync.

Table of Contents