{"record":{"id":"3c1f6bb1b225bfca","repo":"ory/hydra","slug":"errincompatibleversion","errorCode":"ErrIncompatibleVersion","errorMessage":"incompatible version of argon2","messagePattern":"incompatible version of argon2","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"oryx/hasherx/hasher_argon2.go","lineNumber":25,"sourceCode":"\t\"encoding/base64\"\n\t\"fmt\"\n\t\"math\"\n\t\"time\"\n\n\t\"github.com/ory/x/otelx\"\n\n\t\"github.com/inhies/go-bytesize\"\n\t\"go.opentelemetry.io/otel\"\n\t\"go.opentelemetry.io/otel/attribute\"\n\t\"go.opentelemetry.io/otel/codes\"\n\n\t\"github.com/pkg/errors\"\n\t\"golang.org/x/crypto/argon2\"\n)\n\nvar (\n\tErrInvalidHash               = errors.New(\"the encoded hash is not in the correct format\")\n\tErrIncompatibleVersion       = errors.New(\"incompatible version of argon2\")\n\tErrMismatchedHashAndPassword = errors.New(\"passwords do not match\")\n)\n\ntype (\n\t// Argon2Config is the configuration for a Argon2 hasher.\n\tArgon2Config struct {\n\t\t// Memory is the amount of memory to use.\n\t\tMemory bytesize.ByteSize `json:\"memory\"`\n\n\t\t// Iterations is the number of iterations to use.\n\t\tIterations uint32 `json:\"iterations\"`\n\n\t\t// Parallelism is the number of threads to use.\n\t\tParallelism uint8 `json:\"parallelism\"`\n\n\t\t// SaltLength is the length of the salt to use.\n\t\tSaltLength uint32 `json:\"salt_length\"`\n","sourceCodeStart":7,"sourceCodeEnd":43,"githubUrl":"https://github.com/ory/hydra/blob/4174065ffb052799890f7480f5360a877a67ffc1/oryx/hasherx/hasher_argon2.go#L7-L43","documentation":"Argon2 hashes embed a version field (v=19 for argon2 0x13). decodeArgon2idHash returns ErrIncompatibleVersion when the version encoded in the hash differs from the argon2.Version the x/crypto package implements, because the reference implementation cannot safely verify against an unknown version.","triggerScenarios":"Calling Compare (dispatching to argon2) or decodeArgon2idHash with a hash string carrying v=16 (argon2 0x10) or any non-0x13 version; the check `version != argon2.Version` at hash_comparator.go:154 fails.","commonSituations":"Hashes generated years ago with argon2 v1.0 (0x10) and now verified with current x/crypto (0x13 only); hashes produced by other languages/tools defaulting to a different version; migration from an older hasherx/x/crypto dependency.","solutions":["Re-hash affected credentials with the current argon2id implementation (progressive migration: on next successful login with a legacy verifier, store a fresh hash).","Use a verifier that supports the old v=16 version for legacy hashes, then upgrade.","Audit hash generation settings to ensure all new hashes use the default current version (v=19)."],"exampleFix":"// before\n// stored: $argon2id$v=16$m=65536,t=3,p=4$...\nerr := hasherx.Compare(ctx, pw, legacyHash) // ErrIncompatibleVersion\n// after\nok := legacyVerifier(legacyHash, pw)\nif ok {\n  newHash, _ := argon2Hasher.Generate(ctx, pw) // v=19\n  store(user, newHash)\n}","handlingStrategy":"type-guard","validationCode":"func isCurrentArgon2Version(hash string) bool {\n  i := strings.Index(hash, \"v=\")\n  if i < 0 { return false }\n  v, err := strconv.Atoi(strings.SplitN(hash[i+2:], \"$\", 2)[0])\n  return err == nil && v == argon2.Version\n}","typeGuard":null,"tryCatchPattern":"if err := hasherx.Compare(ctx, pw, hash); err != nil {\n  if errors.Is(err, hasherx.ErrIncompatibleVersion) {\n    return upgradeLegacyHash(user, pw) // verify with legacy lib, rehash v=19\n  }\n  return err\n}","preventionTips":["Standardize on argon2 v=19 (current x/crypto default) for all new hashes","During migrations, verify legacy v=16 hashes with a compatible verifier then re-hash","Record hash scheme/version metadata alongside credentials"],"tags":["passwords","hashing","argon2","version-compatibility"],"backgroundTag":"argon2-version-mismatch","analyzedSha":"4174065ffb052799890f7480f5360a877a67ffc1","analyzedAt":"2026-09-03T14:52:41.581Z","contentChangedAt":"2026-09-03T14:52:41.581Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}