hashicorp/nomad · error

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.

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)

Solutions

1. Remove or correct the unsupported capability names in the task's cap_add field
2. Check which capabilities the host supports (e.g. 'capsh --print' or compare with capabilities.Supported()) and align the config
3. If the capability is genuinely needed, move the workload to a host whose kernel supports it
4. 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"]

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
}

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

• cap_drop configured with capabilities not supported by syste
• failed driver config validation: %v
• missing secret ID
• namespace cannot contain template delimiters or parenthesis
• wait config is nil or empty

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