cap_add configured with capabilities not supported by system

Error message

cap_add configured with capabilities not supported by system: %s

What it means

This error is thrown by the Nomad Java driver during task config validation when the cap_add field lists Linux capabilities that the host kernel/system does not support. The driver computes the set of capabilities supported on the system (capabilities.Supported()) and takes its difference with the requested set; any leftover capabilities are reported. This prevents starting tasks that would silently fail or be rejected later by the executor.

Solutions

Remove or correct the unsupported capability names in the task's cap_add field
Check which capabilities the host supports (e.g. 'capsh --print' or compare with capabilities.Supported()) and align the config
If the capability is genuinely needed, move the workload to a host whose kernel supports it
Update Nomad/its capability list if the capability exists but the vendored list is outdated

Example fix

// before
-cap_add = ["CAP_NET_ADMIN", "CAP_SYS_NICE", "CAP_NET_ADMN"]
// after
-cap_add = ["CAP_SYS_NICE"]

Defensive patterns

Strategy: validation

Validate before calling

import "github.com/hashicorp/nomad/client/lib/capabilities"

func checkCapAdd(adds []string) error {
    bad := capabilities.Supported().Difference(capabilities.New(adds))
    if !bad.Empty() {
        return fmt.Errorf("unsupported cap_add: %s", bad)
    }
    return nil
}

Prevention

Keep a vetted allowlist of capabilities per host class and generate job specs from it
Run 'nomad job validate' against the target cluster before submitting
Spell capabilities exactly as in the supported set and add CI checks against the driver schema
Pin capability-needing workloads to eligible nodes with matching kernels via constraints

When it happens

Trigger: A task's drivers.java config (via the TaskConfig's CapAdd field) names a capability not in the system's supported set, e.g. a typo like CAP_NET_ADMN or a capability unavailable on the host kernel, found when taskConfig.validate() runs in StartTask or ValidateTask.

Common situations: Typos in capability names; copying configs between hosts with different kernel versions or seccomp/apparmor restrictions; running Nomad in containers/VMs with a reduced capability set; using newer capabilities (e.g. CAP_CHECKPOINT_RESTORE) on older kernels.

Related errors

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/dd16b05481874af5. Report an issue: GitHub.

Appendix: source

Thrown at drivers/java/driver.go:215

func (tc *TaskConfig) validate() error {
	switch tc.ModePID {
	case "", executor.IsolationModePrivate, executor.IsolationModeHost:
	default:
		return fmt.Errorf("pid_mode must be %q or %q, got %q", executor.IsolationModePrivate, executor.IsolationModeHost, tc.ModePID)

	}

	switch tc.ModeIPC {
	case "", executor.IsolationModePrivate, executor.IsolationModeHost:
	default:
		return fmt.Errorf("ipc_mode must be %q or %q, got %q", executor.IsolationModePrivate, executor.IsolationModeHost, tc.ModeIPC)
	}

	supported := capabilities.Supported()
	badAdds := supported.Difference(capabilities.New(tc.CapAdd))
	if !badAdds.Empty() {
		return fmt.Errorf("cap_add configured with capabilities not supported by system: %s", badAdds)
	}
	badDrops := supported.Difference(capabilities.New(tc.CapDrop))
	if !badDrops.Empty() {
		return fmt.Errorf("cap_drop configured with capabilities not supported by system: %s", badDrops)
	}

	if tc.WorkDir != "" && !filepath.IsAbs(tc.WorkDir) {
		return fmt.Errorf("work_dir must be an absolute path: %s", tc.WorkDir)
	}
	return nil
}

// TaskState is the state which is encoded in the handle returned in
// StartTask. This information is needed to rebuild the taskConfig state and handler
// during recovery.
type TaskState struct {
	ReattachConfig *pstructs.ReattachConfig
	TaskConfig     *drivers.TaskConfig

View on GitHub (pinned to 482b49bf1a)