What causes "LAN RPC returned an error" in tinyhumansai/openhuman?

Run with `DEBUG=transport:lan:error` and reproduce — the raw json.error (with code) is logged

LAN RPC returned an error

Error message

LAN RPC returned an error

What it means

LAN transport's empty-message fallback: the JSON-RPC frame contained an `error` object but `json.error.message` was nullish, so the generic literal is thrown as a plain `Error`. The real error code/message was logged via `logErr('[transport:lan] ← %s error: %s', ...)` and lost to the exception — there is no CoreRpcError-style kind/data propagation on this path.

Source

Thrown at app/src/services/transport/LanHttpTransport.ts:76

    } catch (err) {
      if (controller.signal.aborted) {
        throw new Error(`[transport:lan] ${method} timed out after ${this.timeoutMs}ms`);
      }
      throw err;
    } finally {
      clearTimeout(timeoutId);
    }

    if (!response.ok) {
      const text = await response.text();
      throw new Error(`[transport:lan] HTTP ${response.status}: ${text || response.statusText}`);
    }

    const json = (await response.json()) as JsonRpcResponse<T>;

    if (json.error) {
      logErr('[transport:lan] ← %s error: %s', method, json.error.message);
      throw new Error(json.error.message ?? 'LAN RPC returned an error');
    }
    if (!Object.prototype.hasOwnProperty.call(json, 'result')) {
      throw new Error('[transport:lan] response missing result');
    }

    log('[transport:lan] ← %s id=%d ok', method, id);
    return json.result as T;
  }

  async *stream<T>(
    method: string,
    params: unknown,
    opts?: { signal?: AbortSignal }
  ): AsyncIterable<T> {
    const result = await this.call<T>(method, params, opts);
    yield result;
  }

View on GitHub (pinned to a221052e0d)

Solutions

Run with `DEBUG=transport:lan:error` and reproduce — the raw json.error (with code) is logged
Check the desktop core's log for the matching request id
Update the desktop app / core so both ends share the current error envelope
If you control handlers, never serialize an error without a non-empty message

Defensive patterns

Strategy: try-catch

Try / catch

try { await lan.call(m, p); }
catch (e) {
  if (e instanceof Error && e.message === 'LAN RPC returned an error') {
    logger.warn('empty LAN error frame', { method: m }); // details only in DEBUG=transport:lan:error
  }
  throw e;
}

Prevention

Enable DEBUG=transport:lan:error during LAN development — empty error frames are logged with their code
Keep client and desktop core versions paired together
If you implement core handlers, lint against serializing errors with empty messages

When it happens

Trigger: Desktop core returning an error frame with a missing/blank message (error struct serialization dropping the field), or a version-skewed core whose error envelope changed shape while keeping the `error` key.

Common situations: Older desktop core paired with a newer client; debugging blind spots because the thrown message carries no code — only `DEBUG=transport:lan:error` reveals it.

Related errors

AI-assisted analysis of tinyhumansai/openhuman@a221052e0d (2026-08-16). Data as JSON: /api/errors/16485feffbff1998. Report an issue: GitHub.