{"record":{"id":"8efc9b093c014b52","repo":"hashicorp/nomad","slug":"driver-does-not-allow-the-following-capabilities","errorCode":null,"errorMessage":"driver does not allow the following capabilities: %s","messagePattern":"driver does not allow the following capabilities: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/shared/capabilities/defaults.go","lineNumber":146,"sourceCode":"// capabilities specified in cap_add. The task will not be allowed to add capabilities\n// not set in the allow_caps setting (which by default is the same as the basis).\n//\n// cap_add takes precedence over cap_drop, enabling the common pattern of dropping\n// all capabilities, then adding back the desired smaller set. e.g.\n//\n//\tcap_drop = [\"all\"]\n//\tcap_add = [\"chown\", \"kill\"]\n//\n// Note that the resulting capability names are upper-cased and prefixed with\n// \"CAP_\", which is the expected input for the exec/java driver implementation.\nfunc Calculate(basis *Set, allowCaps, capAdd, capDrop []string) ([]string, error) {\n\tallow := New(allowCaps)\n\tadds := New(capAdd)\n\n\t// determine caps the task wants that are not allowed\n\tmissing := allow.Difference(adds)\n\tif !missing.Empty() {\n\t\treturn nil, fmt.Errorf(\"driver does not allow the following capabilities: %s\", missing)\n\t}\n\n\t// the realized enabled capabilities starts with what is allowed both by driver\n\t// config AND is a member of the basis (i.e. nomad defaults)\n\tresult := basis.Intersect(allow)\n\n\t// then remove capabilities the task explicitly drops\n\tresult.Remove(capDrop)\n\n\t// then add back capabilities the task explicitly adds\n\treturn result.Union(adds).Slice(true), nil\n}\n\n// Delta calculates the set of capabilities that must be added and dropped relative\n// to a basis to achieve a desired result. The use case is that the docker driver\n// assumes a default set (DockerDefault), and we must calculate what to pass into\n// --cap-add and --cap-drop on container creation given the inputs of the docker\n// plugin config for allow_caps, and the docker task configuration for cap_add and","sourceCodeStart":128,"sourceCodeEnd":164,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/shared/capabilities/defaults.go#L128-L164","documentation":"capabilities.Calculate intersects the driver-configured allowed capability set (allowCaps) with the capabilities a task requests via cap_add. If the task requests any capability outside the driver's allowlist, Calculate returns 'driver does not allow the following capabilities: <list>'. This enforces the Nomad allow_caps driver/plugin configuration security boundary.","triggerScenarios":"StartTask (docker driver container config) where the task's cap_add contains caps not present in the driver's allow_caps config (or the plugin's default allowlist).","commonSituations":"Job asks for cap_add = [\"SYS_ADMIN\"] or \"ALL\" while the client's docker plugin allow_caps only permits e.g. NET_BIND_SERVICE/CHOWN/DAC_OVERRIDE; operator tightened allow_caps without updating jobs.","solutions":["Remove the disallowed capabilities from the task's cap_add","Ask the cluster operator to add the needed capability to the docker plugin's allow_caps in client config","Align with the least-privilege default set Nomad permits (basis) instead of requesting broad caps"],"exampleFix":"// before\ncap_add = [\"SYS_ADMIN\"]\n// after\ncap_add = [\"NET_BIND_SERVICE\"]","handlingStrategy":"validation","validationCode":"allowed, err := capabilities.Calculate(driverAllowCaps, taskCapAdd)\nif err != nil {\n    // trim taskCapAdd to allowed set before StartTask\n    taskCapAdd = intersection(taskCapAdd, driverAllowCaps)\n}","typeGuard":null,"tryCatchPattern":"if _, err := capabilities.Calculate(allowCaps, capAdd); err != nil {\n    var missingCaps string\n    fmt.Sscanf(err.Error(), \"driver does not allow the following capabilities: %s\", &missingCaps)\n    // reduce requested caps or update plugin allow_caps\n}","preventionTips":["Keep job cap_add within the client's configured allow_caps","Coordinate allow_caps changes with job authors","Prefer Nomad's default capability basis over broad/ALL requests"],"tags":["capabilities","security","allowlist","nomad","docker"],"backgroundTag":"capability-not-allowed","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"}