{"record":{"id":"d92a68b2dc07992e","repo":"tailscale/tailscale","slug":"error-parsing-config-file-s-unsupported-versio","errorCode":null,"errorMessage":"error parsing config file %s: unsupported \\\"version\\\" value %q; want \\\"alpha0\\\" for now","messagePattern":"error parsing config file (.+?): unsupported \\\\\"version\\\\\" value %q; want \\\\\"alpha0\\\\\" for now","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"ipn/conffile/conffile.go","lineNumber":102,"sourceCode":"\t\t}\n\t} else {\n\t\tc.Std = c.Raw // config file must be valid JSON with ts_omit_hujsonconf\n\t}\n\tvar ver struct {\n\t\tVersion string `json:\"version\"`\n\t}\n\tif err := json.Unmarshal(c.Std, &ver); err != nil {\n\t\tif !buildfeatures.HasHuJSONConf {\n\t\t\treturn nil, fmt.Errorf(\"error parsing config file %s, which must be valid standard JSON: %w\", path, err)\n\t\t}\n\t\treturn nil, fmt.Errorf(\"error parsing config file %s: %w\", path, err)\n\t}\n\tswitch ver.Version {\n\tcase \"\":\n\t\treturn nil, fmt.Errorf(\"error parsing config file %s: no \\\"version\\\" field defined\", path)\n\tcase \"alpha0\":\n\tdefault:\n\t\treturn nil, fmt.Errorf(\"error parsing config file %s: unsupported \\\"version\\\" value %q; want \\\"alpha0\\\" for now\", path, ver.Version)\n\t}\n\tc.Version = ver.Version\n\n\tjd := json.NewDecoder(bytes.NewReader(c.Std))\n\tjd.DisallowUnknownFields()\n\terr = jd.Decode(&c.Parsed)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error parsing config file %s: %w\", path, err)\n\t}\n\tif jd.More() {\n\t\treturn nil, fmt.Errorf(\"error parsing config file %s: trailing data after JSON object\", path)\n\t}\n\treturn &c, nil\n}\n","sourceCodeStart":84,"sourceCodeEnd":117,"githubUrl":"https://github.com/tailscale/tailscale/blob/6e0912f97994f927632b34ae9e63b53d6516a6ac/ipn/conffile/conffile.go#L84-L117","documentation":"The config file declares a \"version\" string, but it is neither the currently-supported \"alpha0\" nor empty. Load only accepts exactly alpha0 at this stage of the format's lifecycle, so anything else — alpha1, 1.0, v2, experimental values — is rejected up front before any field decoding, protecting against silently misreading a newer dialect.","triggerScenarios":"A config written for a different (usually newer or aspirational) version of the format, e.g. \"version\": \"alpha1\" or \"version\": \"1.0\"; downgrading: config file produced by a newer tailscale whose format version bumped past alpha0, then loaded by an older build; typos like \"alphaO\" (letter O) or \"Alpha0\".","commonSituations":"Rolling back a binary while keeping /etc/tailscale config from the newer release; documentation/tutorial referencing a version string that never shipped this build; CI fixtures copied from main-branch tests into older release tests.","solutions":["Set the version to \"alpha0\" — the only value this build accepts","If the file came from a newer tailscale, downgrade the config by hand: re-create it with alpha0 fields, or upgrade the binary to match the file","Check for exact spelling/case: alpha0, all lowercase, no quotes mismatch","Pin your config fixtures to the version supported by the oldest binary you deploy"],"exampleFix":"// before\n{\n  \"version\": \"alpha1\",\n  \"hostname\": \"node-1\"\n}\n\n// after\n{\n  \"version\": \"alpha0\",\n  \"hostname\": \"node-1\"\n}","handlingStrategy":"validation","validationCode":"func supportedVersion(v string) bool {\n    return v == \"alpha0\"\n}","typeGuard":"func versionSupportedByThisBuild(b []byte) bool {\n    var v struct {\n        Version string `json:\"version\"`\n    }\n    _ = json.Unmarshal(b, &v)\n    return supportedVersion(v.Version)\n}","tryCatchPattern":"if v, ok := versionOf(raw); ok && !supportedVersion(v) {\n    return fmt.Errorf(\"config version %q unsupported by this binary; upgrade binary or pin file to alpha0\", v)\n}\ncfg, err := conffile.Load(path)","preventionTips":["Pin configs to the version of the oldest binary in the fleet","Automate config regeneration on binary upgrades/downgrades","Copy the version string verbatim from shipped examples; never retype it","Add a CI check comparing config version against the release's supported set"],"tags":["go","tailscale","config","version","unsupported-version","schema","downgrade"],"backgroundTag":"unsupported-config-version","analyzedSha":"6e0912f97994f927632b34ae9e63b53d6516a6ac","analyzedAt":"2026-08-18T08:17:25.280Z","contentChangedAt":"2026-08-18T08:17:25.280Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}