{"record":{"id":"e7a528ebcdb7bb2f","repo":"XTLS/Xray-core","slug":"failed-to-read-metadata","errorCode":null,"errorMessage":"failed to read metadata","messagePattern":"failed to read metadata","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/mux/server.go","lineNumber":340,"sourceCode":"\n\treturn err\n}\n\nfunc (w *ServerWorker) handleStatusEnd(meta *FrameMetadata, reader *buf.BufferedReader) error {\n\tif s, found := w.sessionManager.Get(meta.SessionID); found {\n\t\ts.Close(false)\n\t}\n\tif meta.Option.Has(OptionData) {\n\t\treturn buf.Copy(NewStreamReader(reader), buf.Discard)\n\t}\n\treturn nil\n}\n\nfunc (w *ServerWorker) handleFrame(ctx context.Context, reader *buf.BufferedReader) error {\n\tvar meta FrameMetadata\n\terr := meta.Unmarshal(reader, session.IsReverseMuxFromContext(ctx))\n\tif err != nil {\n\t\treturn errors.New(\"failed to read metadata\").Base(err)\n\t}\n\n\tswitch meta.SessionStatus {\n\tcase SessionStatusKeepAlive:\n\t\terr = w.handleStatusKeepAlive(&meta, reader)\n\tcase SessionStatusEnd:\n\t\terr = w.handleStatusEnd(&meta, reader)\n\tcase SessionStatusNew:\n\t\terr = w.handleStatusNew(session.ContextWithIsReverseMux(ctx, false), &meta, reader)\n\tcase SessionStatusKeep:\n\t\terr = w.handleStatusKeep(&meta, reader)\n\tdefault:\n\t\tstatus := meta.SessionStatus\n\t\treturn errors.New(\"unknown status: \", status).AtError()\n\t}\n\n\tif err != nil {\n\t\treturn errors.New(\"failed to process data\").Base(err)","sourceCodeStart":322,"sourceCodeEnd":358,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/common/mux/server.go#L322-L358","documentation":"ServerWorker.handleFrame could not unmarshal a frame header: FrameMetadata.Unmarshal failed before any status dispatch. This is the umbrella error for all frame-metadata parse failures (target/source/local address errors, insufficient buffer, bad length prefix), and it terminates the mux connection's read loop.","triggerScenarios":"The first 2-byte length prefix plus payload do not decode as FrameMetadata: stream desync, non-mux bytes fed to the mux server, truncation, or version-incompatible metadata layout.","commonSituations":"Pointing a mux-enabled client at a server that terminates TLS and forwards plain bytes elsewhere, transport-level corruption, or downgrade/mismatch between client/server versions.","solutions":["Look at the Base() error to see which field failed (target address vs source/local vs buffer length) and follow that specific cause.","Confirm both endpoints run the same Xray-core version.","Verify the transport chain (TLS/Reality settings identical on both ends) so the mux layer receives the intended plaintext stream.","Disable mux to confirm the underlying proxy path works, then re-enable and retest."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"err := meta.Unmarshal(reader, rev)\nif err != nil {\n    // inspect chain: errors.New(\"failed to read metadata\").Base(err)\n    cause := err\n    for errors.Unwrap(cause) != nil { cause = errors.Unwrap(cause) }\n    log.Warn(\"mux metadata failed, root cause: \", cause)\n    return err // connection must close\n}","preventionTips":["Unwrap the error chain — the base error names the exact field that failed.","Verify TLS/Reality parameters match on both ends so mux sees clean plaintext.","Test with mux disabled to confirm the underlying path first."],"tags":["mux","protocol","parsing","xray"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}