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.
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:
| Client | Field | Notes |
|---|---|---|
| mihomo ≥ 1.19 | obfs + obfs-password | obfs must be a string |
| Shadowrocket | Obfuscation / Obfuscation Password | two input boxes in the GUI |
| Old Clash (dreamacro) | none | no Hysteria2 support; switch cores |
| sing-box | obfs.type + obfs.password | here 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:
- Get the raw config from the server first, confirm both
finalmask.udp[].typeandsettings.passwordhave values, and watch out for a password that was printed only once and then lost. - Check the client version first. mihomo before 1.19 had incomplete obfs support;
mihomo -vis the fastest check. - Compare field shapes. Whether
obfsis a string — that alone explains most of the errors. - 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
nc -vz host 443to see if the port is reachable (for UDP usenc -vzu)- Whether the server log has a
QUIC handshakeentry - Compare the client obfs parameters character by character
- 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.