{"record":{"id":"f9a38664684e6463","repo":"hashicorp/nomad","slug":"variables-are-limited-to-64kib-in-total-size","errorCode":null,"errorMessage":"variables are limited to 64KiB in total size","messagePattern":"variables are limited to 64KiB in total size","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/variables.go","lineNumber":75,"sourceCode":"\tminVariableLockTTL = 10 * time.Second\n\tmaxVariableLockTTL = 24 * time.Hour\n\n\t// defaultLockTTL is the default value used to maintain a lock before it needs to\n\t// be renewed. The actual value comes from the experience with Consul.\n\tdefaultLockTTL = 15 * time.Second\n\n\t// defaultLockDelay is the default a lock will be blocked after the TTL\n\t// went by without any renews. It is intended to prevent split brain situations.\n\t// The actual value comes from the experience with Consul.\n\tdefaultLockDelay = 15 * time.Second\n)\n\nvar (\n\terrNoPath             = errors.New(\"missing path\")\n\terrNoNamespace        = errors.New(\"missing namespace\")\n\terrNoLock             = errors.New(\"missing lock ID\")\n\terrWildCardNamespace  = errors.New(\"can not target wildcard (\\\"*\\\")namespace\")\n\terrQuotaExhausted     = errors.New(\"variables are limited to 64KiB in total size\")\n\terrNegativeDelayOrTTL = errors.New(\"Lock delay and TTL must be positive\")\n\terrInvalidTTL         = errors.New(\"TTL must be between 10 seconds and 24 hours\")\n)\n\n// VariableMetadata is the metadata envelope for a Variable, it is the list\n// object and is shared data between an VariableEncrypted and a\n// VariableDecrypted object.\ntype VariableMetadata struct {\n\tNamespace string\n\tPath      string\n\n\t// Lock represents a variable which is used for locking functionality.\n\tLock *VariableLock `json:\",omitempty\"`\n\n\tCreateIndex uint64\n\tCreateTime  int64\n\tModifyIndex uint64\n\tModifyTime  int64","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/variables.go#L57-L93","documentation":"VariableDecrypted.ValidateForLock rejects any lock-related variable whose serialized Items exceed the 64KiB (maxVariableSize) limit. Nomad caps the total size of a variable's key/value payload so it stays within raft and RPC size budgets. When the payload is too large, the sentinel errQuotaExhausted is returned instead of storing the variable.","triggerScenarios":"Calling ValidateForLock on a VariableDecrypted whose vd.Items.Size() > maxVariableSize (64KiB); e.g. creating or updating a lock variable whose key/value data totals more than 65536 bytes.","commonSituations":"Storing large config blobs, certificates, or many keys in a single variable; migrating secrets from Vault/consul-template files verbatim into one Nomad variable; accidentally embedding binary data instead of references.","solutions":["Reduce the payload: split the data across multiple variables under different paths so each stays under 64KiB.","Remove unneeded keys or compress/trim large values (store a path/URL to the data instead of the data itself).","Check vd.Items.Size() before calling the API and reject or split oversized payloads in your tooling."],"exampleFix":"// before\nvariable.Items[\"big-config\"] = string(largeJSONBlob) // > 64KiB total\nerr := variable.ValidateForLock()\n// after\nif variable.Items.Size() > 60*1024 {\n\tparts := splitPayload(largeJSONBlob, 32*1024)\n\tfor i, p := range parts {\n\t\tsv := variable.Copy()\n\t\tsv.Path = fmt.Sprintf(\"%s/part%d\", variable.Path, i)\n\t\tsv.Items = map[string]string{\"data\": p}\n\t}\n}","handlingStrategy":"validation","validationCode":"func variableFits(v structs.VariableDecrypted) bool {\n\treturn v.Items.Size() <= structs.MaxVariableSize // 64KiB\n}","typeGuard":null,"tryCatchPattern":"if err := vd.ValidateForLock(); err != nil {\n\tif err.Error() == \"variables are limited to 64KiB in total size\" {\n\t\treturn fmt.Errorf(\"variable %q exceeds 64KiB; split it into smaller variables\", vd.Path)\n\t}\n\treturn err\n}","preventionTips":["Check Items.Size() in tooling before submitting variable writes.","Split large configs across multiple variable paths.","Store references (paths, URLs) instead of raw large blobs."],"tags":["nomad","variables","size-limit","validation"],"backgroundTag":"payload-size-limit-exceeded","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}