ipfs/kubo · error

api version mismatch

Error message

api version mismatch

What it means

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.

Source

Thrown at core/corehttp/commands.go:22

	"errors"
	"fmt"
	"net"
	"net/http"
	"os"
	"strconv"
	"strings"

	cmds "github.com/ipfs/go-ipfs-cmds"
	cmdsHttp "github.com/ipfs/go-ipfs-cmds/http"
	version "github.com/ipfs/kubo"
	oldcmds "github.com/ipfs/kubo/commands"
	config "github.com/ipfs/kubo/config"
	"github.com/ipfs/kubo/core"
	corecommands "github.com/ipfs/kubo/core/commands"
	"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)

var errAPIVersionMismatch = errors.New("api version mismatch")

const (
	originEnvKey          = "API_ORIGIN"
	originEnvKeyDeprecate = `You are using the ` + originEnvKey + `ENV Variable.
This functionality is deprecated, and will be removed in future versions.
Instead, try either adding headers to the config, or passing them via
cli arguments:

	ipfs config API.HTTPHeaders --json '{"Access-Control-Allow-Origin": ["*"]}'
	ipfs daemon
`
)

// APIPath is the path at which the API is mounted.
const APIPath = "/api/v0"

var defaultLocalhostOrigins = []string{
	"http://127.0.0.1:<port>",

View on GitHub (pinned to 329838acdf)

Solutions

1. Upgrade (or downgrade) the client library so its version matches the daemon's.
2. Rebuild/reinstall tools that embed the kubo client after upgrading the daemon.
3. Verify versions with `ipfs version` on both sides; the mismatch is printed in the error body.
4. If you control the client, use a neutral User-Agent only if you genuinely handle API drift yourself (not recommended for kubo clients).

Example fix

// before
daemon v0.30.0 vs client built from kubo v0.25.0 -> 400 api version mismatch (v0.30.0 != v0.25.0)
// after
go get github.com/ipfs/kubo@v0.30.0 && go build ./...  # client matches daemon

daemonVer, err := shell.Version() // http://host:5001/api/v0/version
if err != nil {
	return err
}
if daemonVer != expectedClientVersion {
	return fmt.Errorf("daemon %s != client %s; upgrade client", daemonVer, expectedClientVersion)
}

resp, err := shell.Post(ctx, "id", nil, nil)
if err != nil && strings.Contains(err.Error(), "api version mismatch") {
	return fmt.Errorf("RPC client incompatible with daemon: %w; rebuild against matching kubo version", err)
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• %s (%s != %s)
• unexpected redirect
• Kubo RPC Access Denied: Please provide a valid authorization
• ipfs api address could not be found
• unsupported file type '%s'

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/9c5c5e972dcff8b7. Report an issue: GitHub.