Troubleshooting

Overview

A Bench that has been flashed and powered on should reach VSEC and show as Online within about 10 minutes. When it does not, the cause is almost always one of four things: incorrect Wi-Fi credentials, a pre-authentication key that has already been used, a network or firewall restriction between the Bench and VSEC, or a power or SD card fault.

This page explains how to identify which one you are facing, and what to send to support if you cannot resolve it yourself.

Bench Status Meanings

The status shown next to a Bench in the Benches list tells you how far the device got, which narrows the problem considerably.

First Checks

Work through these before collecting logs. They resolve the majority of cases.

1. Verify the Wi-Fi SSID and password. Roughly 90% of connectivity issues are a typo in one of these two fields. Check for a trailing space, a swapped character, or the wrong network name.
2. Confirm the WAN interface matches reality. A Bench configured for wlan0 will not connect over an Ethernet cable, and vice versa.
3. Confirm the Wi-Fi country code. An incorrect regulatory domain can prevent the radio from using the channel your access point is on.
4. Check the power supply. Use the official 15.3W USB-C supply. Undervoltage causes intermittent failures that look like network problems.
5. Re-seat the SD card and confirm the image was written successfully by Raspberry Pi Imager.
6. Wait the full 10 minutes, then restart once. First boot includes filesystem expansion and provisioning, so it is slower than later boots. If the Bench has not appeared after 10 minutes, power cycle it and give it another 10.
7. Attach a screen and keyboard if you have physical access. The console output during boot often names the failure directly.

Collecting the Network Debug Log

Every Bench writes a network debug log to the boot partition of its SD card. This is the primary diagnostic artifact and the first thing support will ask for.

1. Power down the Bench and remove the SD card.
2. Insert the SD card into your computer. The first partition, the FAT32 boot partition, mounts automatically on Windows and macOS as a removable drive (e.g. D:\).
3. Copy network-debug.log from the root of that partition. It sits alongside vsec_config.txt.
4. Re-insert the SD card into the Bench and power it back on.

D:\network-debug.log

Reading the Network Debug Log

The log records network interface activity during boot. You are looking for three milestones, in order. Whichever one is missing tells you where provisioning stopped.

A successful boot

All three milestones are present, and the tunnel comes up within seconds of the network being ready:

NetworkManager[722]: device (wlan0): Activation: (wifi) Stage 2 of 5 (Device Configure) successful. Connected to wireless network "LabNetwork"
NetworkManager[722]: dhcp4 (wlan0): state changed new lease, address=192.168.0.45
NetworkManager[722]: manager: NetworkManager state is now CONNECTED_GLOBAL
NetworkManager[722]: manager: startup complete
NetworkManager[722]: device (tailscale0): state change: config -> ip-config (reason 'none', managed-type: 'external')
NetworkManager[722]: device (tailscale0): Activation: successful, device activated.

A failed registration

The Wi-Fi and DHCP milestones succeed, and the tailscale0 interface is created but never activates. There is no Activation: successful line for it, and no further progress no matter how long the device runs:

NetworkManager[725]: manager: (tailscale0): new Tun device (/org/freedesktop/NetworkManager/Devices/6)
NetworkManager[725]: device (wlan0): Activation: (wifi) Stage 2 of 5 (Device Configure) successful. Connected to wireless network "LabNetwork"
NetworkManager[725]: dhcp4 (wlan0): state changed new lease, address=192.168.0.45
NetworkManager[725]: manager: NetworkManager state is now CONNECTED_GLOBAL
NetworkManager[725]: manager: startup complete

This is the signature of a Bench stuck on Pending. The device is on the network and has internet access, but it never completed registration with VSEC.

Common Causes and Fixes

Incorrect Wi-Fi credentials

The most frequent cause by a wide margin. The Bench cannot report a bad password back to you, so the symptom is silence.

Fix: Correct the ssid and password values in vsec_config.txt on the boot partition. See Manual Configuration for the file format and editing steps.

Expired or already-used pre-authentication key

The preAuthKey in vsec_config.txt registers the Bench with the VPN server. It is unique and typically single-use. A key that has expired or has already been consumed by a previous boot will not register, and the Bench stays on Pending indefinitely.

This is the usual explanation when the log shows a healthy network but no tunnel activation.

Fix: Create a new Bench entry in VSEC to generate a fresh key, download the new image or configuration file, and re-flash or re-apply it to the SD card. Editing the existing key by hand will not help, as the key itself is what has been used up.

Network and Firewall Restrictions

Corporate and lab networks are the second major cause of a Bench that never registers. The device reaches the local network and gets an IP address, so everything looks healthy from the log’s perspective, but the outbound connection to VSEC is blocked before it arrives.

Common culprits on a company network:

What your network team needs to allow. Share this with whoever administers your firewall:

• Outbound HTTPS (TCP 443) from the Bench to the VPN server hostname in the loginURL field of vsec_config.txt, and to *.vsec.blockharbor.io
• Outbound UDP from the Bench for the VPN tunnel, for best performance
• No TLS interception or certificate re-signing on that traffic
• Outbound DNS resolution for the above hostnames

Known firewall behaviour by vendor

Most firewalls need no changes at all. The Bench uses NAT traversal to establish its tunnel, which works through the majority of firewalls without configuration.

Where a direct connection cannot be made, the tunnel falls back to relay servers. The Bench still comes online and works normally, it just sees higher latency. A Bench connecting through a relay is not a fault, and does not need fixing unless test throughput is affected.

The table below summarises the behaviour reported for common firewall platforms. Vendors not listed generally work without changes.

For the full vendor detail behind this table, including the exact configuration screens and settings, see the upstream Tailscale firewall integration documentation. The Bench VPN is built on Tailscale, so that guidance applies directly.

Isolating a network problem

The fastest way to prove or rule out a firewall is to change the network and nothing else.

1. Create a mobile phone Wi-Fi hotspot.
2. Update the Wi-Fi credentials in vsec_config.txt to point the Bench at the hotspot. See Manual Configuration.
3. Boot the Bench and wait 10 minutes.

If the Bench comes Online on the hotspot but not on the company network, the company network is blocking the connection, and the fix is a firewall rule rather than anything on the device. If it fails on both, the problem is with the Bench configuration or the pre-authentication key.

Static IP misconfiguration

When useDHCP is false, an incorrect gateway or DNS server will leave the Bench on the network with no route to the internet. The log shows the interface activating without a DHCP lease, and the tunnel never comes up.

Fix: Set useDHCP to true to confirm the rest of the configuration works, then reintroduce the static settings once the Bench has come online at least once.

Bench goes Offline after working

A Bench that has been Online and then drops is a stability problem, not a provisioning one. The credentials and firewall rules are known good.

Check for:

• Loss of power, or a power supply that cannot sustain load
• Marginal Wi-Fi signal strength at the Bench’s location, or access point roaming
• DHCP lease expiry with an address change
• The device having simply been switched off or unplugged

Where the drop is intermittent, leave the Bench running and collect a log that spans the disconnection rather than one from a fresh boot.

Sending the Log to Support

If the checks above do not resolve the issue, send the log to us. Following these steps in order gives us everything we need in one message, which avoids several days of back and forth.

Step 1: Note the Bench name and workspace

Open the Benches list in VSEC Test and write down the Bench name and the workspace it belongs to, exactly as they appear. Take a screenshot if it is easier.

Step 2: Power down the Bench and remove the SD card

Shut the Bench down cleanly, disconnect the power, and take the SD card out.

Step 3: Insert the SD card into your computer

The first partition, the FAT32 boot partition, mounts automatically as a removable drive on Windows and macOS. On Windows it appears as a drive letter such as D:\.

Step 4: Copy network-debug.log off the card

It sits in the root of that partition, next to vsec_config.txt:

D:\network-debug.log

Copy it to your Desktop or another working folder. Copy it, do not move or delete it from the card.

Step 5: Safely eject the card and put the Bench back online

Eject the SD card, re-insert it into the Bench, and power the Bench back on. Leave it running.

Step 6: Send the log to support

Contact support with network-debug.log attached, and include the details below in your message.

Step 7: Leave the Bench running while we investigate

Keep the Bench powered on and connected once your request is in. If you would like to try something else in the meantime, that is fine, just let us know what you changed, and change one thing at a time so it stays clear which change made the difference.

Related