{"record":{"id":"0c8fb5a5042159f4","repo":"hashicorp/nomad","slug":"variable-not-found","errorCode":null,"errorMessage":"variable not found","messagePattern":"variable not found","errorType":"error_code","errorClass":"ErrVariablePathNotFound","httpStatus":null,"severity":"warning","filePath":"api/variables.go","lineNumber":25,"sourceCode":"\t\"encoding/json\"\n\t\"errors\"\n\t\"fmt\"\n\t\"maps\"\n\t\"net/http\"\n\t\"strings\"\n)\n\nconst (\n\t// ErrVariableNotFound was used as the content of an error string.\n\t//\n\t// Deprecated: use ErrVariablePathNotFound instead.\n\tErrVariableNotFound = \"variable not found\"\n)\n\nvar (\n\t// ErrVariablePathNotFound is returned when trying to read a variable that\n\t// does not exist.\n\tErrVariablePathNotFound = errors.New(\"variable not found\")\n)\n\n// Variables is used to access variables.\ntype Variables struct {\n\tclient *Client\n}\n\n// Variables returns a new handle on the variables.\nfunc (c *Client) Variables() *Variables {\n\treturn &Variables{client: c}\n}\n\n// Create is used to create a variable.\nfunc (vars *Variables) Create(v *Variable, qo *WriteOptions) (*Variable, *WriteMeta, error) {\n\tv.Path = cleanPathString(v.Path)\n\tvar out Variable\n\twm, err := vars.client.put(\"/v1/var/\"+v.Path, v, &out, qo)\n\tif err != nil {","sourceCodeStart":7,"sourceCodeEnd":43,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/api/variables.go#L7-L43","documentation":"ErrVariablePathNotFound is the sentinel error (message \"variable not found\") returned by Variables().Read and Variables().GetVariableItems when the queried variable path does not exist on the server — the API returns no variable and readInternal yields a nil v. It is exported so callers can compare with errors.Is instead of matching strings.","triggerScenarios":"Calling client.Variables().Read(path, q) or GetVariableItems(path, q) for a path that was never created or was deleted/purged; reading a path in a namespace where it doesn't exist; a typo in the variable path (e.g. wrong namespace prefix or missing 'nomad/jobs' segment).","commonSituations":"Job templates reading variables whose path was misconfigured; CI reading a variable before the provisioning step that creates it; ACL/namespace differences making an existing variable invisible to the caller's token; GC removing stale job variables.","solutions":["Verify the exact variable path (including namespace and 'nomad/jobs/...' prefix) with nomad var list or the UI.","Create the variable first via Create/Update (or `nomad var put`) before reading.","Compare with errors.Is(err, api.ErrVariablePathNotFound) and provide a default/fallback instead of failing.","Check the QueryOptions.Namespace matches where the variable lives, and that the token's ACL grants read on it."],"exampleFix":"// before\nv, _, err := client.Variables().Read(\"nomad/jobs/app/config\", nil)\nif err != nil { return err }\n// after\nv, _, err := client.Variables().Read(\"nomad/jobs/app/config\", nil)\nif errors.Is(err, api.ErrVariablePathNotFound) {\n    v = defaultVar // fall back when the variable doesn't exist yet\n} else if err != nil {\n    return err\n}","handlingStrategy":"type-guard","validationCode":"import \"errors\"\nimport \"github.com/hashicorp/nomad/api\"\n\n// pre-check via List to see if the path exists\nvars, _, err := client.Variables().List(nil, nil)\nexists := false\nif err == nil {\n    for _, v := range vars {\n        if v.Path == \"nomad/jobs/app/config\" { exists = true; break }\n    }\n}","typeGuard":"func isVarNotFound(err error) bool {\n    return errors.Is(err, api.ErrVariablePathNotFound)\n}","tryCatchPattern":"v, _, err := client.Variables().Read(path, nil)\nswitch {\ncase errors.Is(err, api.ErrVariablePathNotFound):\n    v = createOrUseDefault(path)\ncase err != nil:\n    return err\n}","preventionTips":["Always use errors.Is(err, api.ErrVariablePathNotFound) rather than string comparison.","Create variables (nomad var put) before jobs/templates that read them.","Double-check path spelling, namespace, and required prefixes like nomad/jobs/.","Verify the ACL token can read the variable in the target namespace."],"tags":["nomad","variables","not-found","kv-store"],"backgroundTag":"resource-not-found","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"}