{"record":{"id":"9c5c5e972dcff8b7","repo":"ipfs/kubo","slug":"api-version-mismatch","errorCode":null,"errorMessage":"api version mismatch","messagePattern":"api version mismatch","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/corehttp/commands.go","lineNumber":22,"sourceCode":"\t\"errors\"\n\t\"fmt\"\n\t\"net\"\n\t\"net/http\"\n\t\"os\"\n\t\"strconv\"\n\t\"strings\"\n\n\tcmds \"github.com/ipfs/go-ipfs-cmds\"\n\tcmdsHttp \"github.com/ipfs/go-ipfs-cmds/http\"\n\tversion \"github.com/ipfs/kubo\"\n\toldcmds \"github.com/ipfs/kubo/commands\"\n\tconfig \"github.com/ipfs/kubo/config\"\n\t\"github.com/ipfs/kubo/core\"\n\tcorecommands \"github.com/ipfs/kubo/core/commands\"\n\t\"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp\"\n)\n\nvar errAPIVersionMismatch = errors.New(\"api version mismatch\")\n\nconst (\n\toriginEnvKey          = \"API_ORIGIN\"\n\toriginEnvKeyDeprecate = `You are using the ` + originEnvKey + `ENV Variable.\nThis functionality is deprecated, and will be removed in future versions.\nInstead, try either adding headers to the config, or passing them via\ncli arguments:\n\n\tipfs config API.HTTPHeaders --json '{\"Access-Control-Allow-Origin\": [\"*\"]}'\n\tipfs daemon\n`\n)\n\n// APIPath is the path at which the API is mounted.\nconst APIPath = \"/api/v0\"\n\nvar defaultLocalhostOrigins = []string{\n\t\"http://127.0.0.1:<port>\",","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/corehttp/commands.go#L4-L40","documentation":"errAPIVersionMismatch is the sentinel message used by the RPC commands middleware when a kubo/go-ipfs client's version string differs from the daemon's: the middleware responds 400 with \"api version mismatch (<daemon> != <client>)\". It protects callers from silently invoking RPC endpoints whose request/response shape changed between versions. Non-kubo user agents skip the check.","triggerScenarios":"An HTTP RPC client whose User-Agent contains \"/go-ipfs/\" or \"/kubo/\" and a version differing from the daemon's calls /api/v0/... (other than the version endpoint). Typically a bundled client library older or newer than the running daemon.","commonSituations":"ipfs-cluster or other tooling built against an older kubo client talking to a newly upgraded daemon; after `ipfs upgrade` where client libraries were not rebuilt; Docker setups mixing image versions.","solutions":["Upgrade (or downgrade) the client library so its version matches the daemon's.","Rebuild/reinstall tools that embed the kubo client after upgrading the daemon.","Verify versions with `ipfs version` on both sides; the mismatch is printed in the error body.","If you control the client, use a neutral User-Agent only if you genuinely handle API drift yourself (not recommended for kubo clients)."],"exampleFix":"// before\ndaemon v0.30.0 vs client built from kubo v0.25.0 -> 400 api version mismatch (v0.30.0 != v0.25.0)\n// after\ngo get github.com/ipfs/kubo@v0.30.0 && go build ./...  # client matches daemon","handlingStrategy":"retry","validationCode":"daemonVer, err := shell.Version() // http://host:5001/api/v0/version\nif err != nil {\n\treturn err\n}\nif daemonVer != expectedClientVersion {\n\treturn fmt.Errorf(\"daemon %s != client %s; upgrade client\", daemonVer, expectedClientVersion)\n}","typeGuard":null,"tryCatchPattern":"resp, err := shell.Post(ctx, \"id\", nil, nil)\nif err != nil && strings.Contains(err.Error(), \"api version mismatch\") {\n\treturn fmt.Errorf(\"RPC client incompatible with daemon: %w; rebuild against matching kubo version\", err)\n}","preventionTips":["Probe /api/v0/version at startup and compare with the client's embedded version","Keep client libraries and daemons deployed from the same release","In mixed environments, upgrade the daemon and clients together; rebuild embedders after upgrades"],"tags":["http","rpc","versioning","compatibility"],"backgroundTag":"api-version-mismatch","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}