Bobay Stack

Networking & proxies / 2026-10-18

Hysteria2 finalmask and mihomo: Two Hours Lost to a Type Error

The server had salamander obfs enabled; the client yaml used a nested map. mihomo only said obfs expected type string, and the rest was guesswork.

4 MIN READ BY BOBAY.TOP Updated 2026-10-23 ↖ All notes
Hysteria2 finalmask and mihomo: Two Hours Lost to a Type Error

I enabled Hysteria2 obfs in 3x-ui on the server, with the parameter salamander. The browser could connect to the node, but mihomo on my local machine refused to start, and the log had just one line:

initialise HTTP proxy: proxies[0]: 'obfs' expected type 'string'

That error actually carries a lot of information — I just wasn't thinking about format at the time.

Two ways to write it, one level of nesting apart

On the server, finalmask is an array, with the obfs type in type:

{
  "finalmask": {
    "udp": [
{ "type": "salamander", "settings": { "password": "<obfuscation password>" } }
    ]
  }
}

mihomo's client config, by contrast, takes a flat string, not an object:

proxies:
  - name: hy2-node
    type: hysteria2
server: <address>
    port: 443
password: <auth password>
obfs: salamander          # string, not a map
obfs-password: <obfuscation password>
sni: <domain>
    skip-cert-verify: false

What I had written was a straight copy of the server structure:

    obfs:
      type: salamander
      password: xxx

So obfs expected a string, got a map, and parsing failed outright. Switching back to a single-line string fixed it immediately.

Different clients call it different things

Same concept, three clients, three names — easy to get stuck when cross-checking the docs:

ClientFieldNotes
mihomo ≥ 1.19obfs + obfs-passwordobfs must be a string
ShadowrocketObfuscation / Obfuscation Passwordtwo input boxes in the GUI
Old Clash (dreamacro)noneno Hysteria2 support; switch cores
sing-boxobfs.type + obfs.passwordhere it is an object structure

That last row is one source of the trap: sing-box uses an object, mihomo uses a string. Both projects keep evolving, and copying one field wrong wastes the whole investigation.

Troubleshooting order

These days I go in this order and usually pinpoint it within ten minutes:

  1. Get the raw config from the server first, confirm both finalmask.udp[].type and settings.password have values, and watch out for a password that was printed only once and then lost.
  2. Check the client version first. mihomo before 1.19 had incomplete obfs support; mihomo -v is the fastest check.
  3. Compare field shapes. Whether obfs is a string — that alone explains most of the errors.
  4. Only then suspect the UDP path. When intermediate devices drop UDP between server and client, the handshake times out instead of reporting a config error — a completely different symptom, so don't troubleshoot them together.

A side conclusion

Obfs is not encryption. It only makes traffic patterns look more like random data, bypassing some fingerprint-based detection, but it provides no confidentiality. What actually protects the content is TLS and the auth password. Keep the two straight and you won't waste judgment on questions like "does enabling obfs make me secure?"

What finalmask actually solves

QUIC handshake packets have a distinctive fingerprint, and some networks rate-limit or drop connections where the first packet is already large. finalmask wraps another layer of obfuscation around QUIC so the byte distribution of the first packet doesn't look like QUIC.

It is obfuscation, not encryption — the real encryption is still at the QUIC/TLS layer. Don't treat it as a "security enhancement"; it only affects whether you can connect at all.

Configuration points

listen: :443
tls:
  cert: /etc/hysteria/cert.pem
  key:  /etc/hysteria/key.pem
obfs:
  type: salamander
  salamander:
password: <long random string>

The client must use exactly the same obfs type and password. Get one character wrong and the symptom is: TCP connects, the QUIC handshake times out, and there is no clear error in the log — that's where "one type error costs two hours" comes from.

Troubleshooting order

  1. nc -vz host 443 to see if the port is reachable (for UDP use nc -vzu)
  2. Whether the server log has a QUIC handshake entry
  3. Compare the client obfs parameters character by character
  4. Try a different port (some networks block 443/UDP)

Item 4 often gets skipped, but it's the only way to distinguish "misconfigured" from "path blocked".

A tradeoff

Enabling obfs adds roughly 3–5% CPU and a bit of latency. Enable it only on links that are rate-limited or dropping packets; on a LAN or a clean link it isn't necessary.

One-line summary: writing down "where it broke" together with "how to verify it" is more useful than writing down only the config — config can be copied; the order of judgment cannot.

Hysteria2mihomoobfsclient compatibility

References

mihomo configuration docs ↗ Hysteria2 obfuscation documentation ↗