shadowsocks/shadowsocks-rust · error

invalid online config version

Error message

invalid online config version

What it means

Thrown when validating a SIP008 online config: the `version` field must be exactly 1 (per SIP008 spec at shadowsocks.org/doc/sip008.html). Any other numeric version is rejected with ErrorKind::Invalid.

Source

Thrown at crates/shadowsocks-service/src/config.rs:2115

                        nconfig.local.push(local_instance);
                    }
                }
            }
            ConfigType::Server | ConfigType::Manager => {
                // NOTE: IGNORED.
                // servers only uses `local_address` for binding outbound interfaces
                //
                // This behavior causes lots of confusion. use outbound_bind_addr instead
            }
            #[cfg(feature = "local-online-config")]
            ConfigType::OnlineConfig => {
                // SIP008. https://shadowsocks.org/doc/sip008.html
                // "version" should be set to "1"
                match config.version {
                    Some(1) => {}
                    Some(v) => {
                        let err = Error::new(
                            ErrorKind::Invalid,
                            "invalid online config version",
                            Some(format!("version: {v}")),
                        );
                        return Err(err);
                    }
                    None => {
                        warn!(
                            "OnlineConfig \"version\" is missing in the configuration, assuming it is a compatible version for this project"
                        );
                    }
                }
            }
        }

        let server_source = match config_type {
            ConfigType::Local | ConfigType::Server | ConfigType::Manager => ServerSource::Configuration,
            #[cfg(feature = "local-online-config")]

View on GitHub (pinned to 8eb0f0a65b)

Solutions

1. Set `"version": 1` (integer) in the SIP008 JSON document
2. Ask the config provider to emit SIP008 version 1
3. If hand-editing, ensure version is a JSON number, not a string

Example fix

// before
{"version": 2, "servers": [...]}
// after
{"version": 1, "servers": [...]}

fn check_sip008_version(doc: &serde_json::Value) -> Result<(), String> {
    match doc.get("version") {
        Some(serde_json::Value::Number(n)) if n.as_i64() == Some(1) => Ok(()),
        other => Err(format!("expected version 1 (integer), got {:?}", other)),
    }
}

match Config::load_from_json(...) { Err(e) if format!("{e}").contains("online config version") => sanitize_and_retry(), ... }

When it happens

Trigger: Calling Config::load_from_json (ConfigType::OnlineConfig) with a JSON document whose `version` is 0, 2, a string like "1", or absent-but-nonconforming value.

Common situations: Third-party SIP008 providers emitting version 2 or omitting/bumping the field; hand-written JSON with `"version": "1"` (string, not integer); auto-generated configs from newer/older tooling.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• `protocol` invalid
• `local_port` cannot be 0
• `local_udp_port` cannot be 0
• invalid `mode`
• `tcp_redir` invalid

AI-assisted analysis of shadowsocks/shadowsocks-rust@8eb0f0a65b (2026-09-09). Data as JSON: /api/errors/51c21d341c63658d. Report an issue: GitHub.