release: v1.4.6

Fixed: removing a chain / Server link now persists. Clearing a node's
"Chain via" relay or its optional Server link never saved — the form sent
the cleared field as `undefined`, which JSON.stringify drops, so it never
reached the PATCH body and the backend's model_dump(exclude_unset=True)
kept the old value. The form now sends an explicit `null`; the backend
already distinguished omitted from null, so this is a frontend-only fix
(chain_node_id and server_id).

Fixed: speed test surfaces the real xray error. A node test that could not
start its throwaway xray always returned a generic "Failed to start temp
xray", hiding the cause. _start_temp_xray now propagates xray's own error
into the result, so the UI shows the actionable reason (e.g. invalid
reality shortId, empty publicKey).

Frontend tsc + build clean; nothing calls _start_temp_xray outside
speedtest_node. No schema migration, no new dependencies, no breaking
changes.

Author: DaveBugg

CHANGELOG.md

@@ -4,6 +4,25 @@ All notable user-facing changes to PiTun. Full per-release detail lives in the
 [GitHub Releases](https://github.com/DaveBugg/PiTun/releases); this file is the
 committed summary.
 
+## v1.4.6 — 2026-07-03
+
+Two fixes from field-testing multi-hop chains: removing a node's chain (or its
+Server link) now actually saves, and a failed speed test now tells you *why*
+instead of a blank "couldn't start".
+
+### Fixed
+
+- **Removing a chain / Server link now persists.** Clearing a node's *"Chain via"*
+  relay (or its optional Server link) never stuck — you could add a chain but never
+  remove it. The form sent the cleared field as `undefined`, which `JSON.stringify`
+  drops, so it never reached the `PATCH` body and the backend's
+  `model_dump(exclude_unset=True)` kept the old value. The form now sends an explicit
+  `null`, which the backend nulls out correctly. Affects `chain_node_id` and `server_id`.
+- **Speed test surfaces the real xray error.** A node test that couldn't start its
+  throwaway xray always showed a generic *"Failed to start temp xray"*, hiding the
+  cause. `_start_temp_xray` now propagates xray's own error into the result, so the UI
+  shows the actionable reason — e.g. `xray: invalid "shortId"` or `xray: empty publicKey`.
+
 ## v1.4.5 — 2026-06-18
 
 Node-circle rotation that no longer drops connections, a fix so switching the

backend/app/config.py

@@ -5,7 +5,7 @@
 # OpenAPI metadata, `/health` response, and `/system/status` so the
 # frontend can display it next to the xray version. Bump this on each
 # release — frontend keeps its own version in `frontend/package.json`.
-APP_VERSION = "1.4.5"
+APP_VERSION = "1.4.6"
 
 
 class Settings(BaseSettings):

backend/app/core/speedtest.py

@@ -87,9 +87,9 @@ async def speedtest_node(node: Node) -> Dict:
         if not resolved_urls:
             return _result(node, error="Failed to resolve any test URL")
 
-        socks_port, proc, tmp_path = await _start_temp_xray(node, chain, entry_ip)
+        socks_port, proc, tmp_path, start_err = await _start_temp_xray(node, chain, entry_ip)
         if proc is None:
-            return _result(node, error="Failed to start temp xray")
+            return _result(node, error=start_err or "Failed to start temp xray")
 
         return await _run_curl_speedtest(node, socks_port, resolved_urls)
 
@@ -151,7 +151,7 @@ async def _resolve_test_urls() -> List[Tuple[str, str, str, int]]:
 
 async def _start_temp_xray(
     node: Node, chain: List[Node], entry_ip: Optional[str]
-) -> Tuple[int, Optional[asyncio.subprocess.Process], Optional[str]]:
+) -> Tuple[int, Optional[asyncio.subprocess.Process], Optional[str], Optional[str]]:
     """
     Start a minimal xray instance bound to 127.0.0.1:<random>.
 
@@ -189,7 +189,7 @@ async def _start_temp_xray(
             outbounds_chain.append(ob)
     except Exception as exc:
         logger.warning("Cannot build chain outbounds for node %d: %s", node.id, exc)
-        return 0, None, None
+        return 0, None, None, f"chain build error: {exc}"
 
     final_tag = outbounds_chain[-1]["tag"]
 
@@ -241,9 +241,13 @@ async def _start_temp_xray(
             err = (stderr_data or stdout_data or b"").decode(errors="replace")[-300:]
             logger.warning("Temp xray for node %d died early: %s", node.id, err)
             _safe_unlink(tmp_path)
-            return 0, None, None
+            # Surface the real reason (last segment of xray's error chain) to
+            # the UI instead of a generic "failed to start" — e.g. an invalid
+            # reality shortId or empty publicKey is otherwise invisible.
+            reason = err.strip().rsplit(">", 1)[-1].strip() or "xray exited early"
+            return 0, None, None, f"xray: {reason}"
         if await _port_open("127.0.0.1", socks_port):
-            return socks_port, proc, tmp_path
+            return socks_port, proc, tmp_path, None
         await asyncio.sleep(0.15)
 
     # Timed out waiting for port — still alive but unresponsive

frontend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pitun-frontend",
   "private": true,
-  "version": "1.4.5",
+  "version": "1.4.6",
   "license": "BSD-3-Clause",
   "type": "module",
   "scripts": {

frontend/src/components/NodeForm.tsx

@@ -81,8 +81,12 @@ export function NodeForm({ initial, onSave, onCancel, loading, nodes = [] }: Pro
     onSave({
       ...form,
       order: initial?.order ?? 0,
-      chain_node_id: chainNodeId ? Number(chainNodeId) : undefined,
-      server_id: serverId ? Number(serverId) : undefined,
+      // Send an explicit `null` (not `undefined`) when cleared — `undefined`
+      // is dropped by JSON.stringify, so the field never reaches the PATCH
+      // body and the backend's `model_dump(exclude_unset=True)` leaves the
+      // old value in place (you could set a chain but never remove it).
+      chain_node_id: chainNodeId ? Number(chainNodeId) : null,
+      server_id: serverId ? Number(serverId) : null,
     })
   }
 

frontend/src/types/index.ts

@@ -70,10 +70,10 @@ export interface Node {
   last_check?: string
   is_online: boolean
   order: number
-  chain_node_id?: number
+  chain_node_id?: number | null
   // Optional link to a Server (the VPS hosting this node's upstream).
   // Purely informational — does not affect routing/connection.
-  server_id?: number
+  server_id?: number | null
   // Optional link to a DeploymentClient — set on Nodes that were
   // exported from a multi-client server-side deployment (WireGuard).
   // Drives the "from server X" source label and the orphan badge.