VictoriaMetrics/VictoriaMetrics · warning

skipping unexpected role=%q; must be one of `tasks`, `servic

Error message

skipping unexpected role=%q; must be one of `tasks`, `services` or `nodes`

What it means

GetLabels dispatches on sdc.Role and only recognizes `tasks`, `services` or `nodes`; anything else returns this error. Docker Swarm roles map to different API endpoints, so an unknown role cannot be queried. This is a validation error in the SD config, surfaced during discovery instead of silently returning zero targets.

Source

Thrown at lib/promscrape/discovery/dockerswarm/dockerswarm.go:53

	Name   string   `yaml:"name"`
	Values []string `yaml:"values"`
}

// GetLabels returns dockerswarm labels according to sdc.
func (sdc *SDConfig) GetLabels(baseDir string) ([]*promutil.Labels, error) {
	cfg, err := getAPIConfig(sdc, baseDir)
	if err != nil {
		return nil, fmt.Errorf("cannot get API config: %w", err)
	}
	switch sdc.Role {
	case "tasks":
		return getTasksLabels(cfg)
	case "services":
		return getServicesLabels(cfg)
	case "nodes":
		return getNodesLabels(cfg)
	default:
		return nil, fmt.Errorf("skipping unexpected role=%q; must be one of `tasks`, `services` or `nodes`", sdc.Role)
	}
}

// MustStop stops further usage for sdc.
func (sdc *SDConfig) MustStop() {
	v := configMap.Delete(sdc)
	if v != nil {
		cfg := v.(*apiConfig)
		cfg.client.Stop()
	}
}

View on GitHub (pinned to 5079fb58f1)

Solutions

1. Set role to exactly one of: tasks, services, nodes (lowercase)
2. Check for typos and surrounding whitespace/quotes in the YAML value
3. Validate the config with the config-check flag before reload
4. Consult the dockerswarm SD docs for the role you actually want

Example fix

// before
- role: task
// after
- role: tasks

// Go: assert role membership before building the SD config
var validRoles = map[string]bool{"tasks": true, "services": true, "nodes": true}
if !validRoles[role] {
    return fmt.Errorf("role %q invalid: must be tasks, services or nodes", role)
}

null

null

When it happens

Trigger: dockerswarm SD config's `role` field is empty, misspelled (e.g. 'task', 'Services', 'container'), or set to a value not in {tasks, services, nodes}.

Common situations: Copy-pasted config from a generic Docker SD example; YAML key edited by hand; older configs using a role name that never existed in this library; case sensitivity mistakes.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• cannot parse proxy auth config: %w
• cannot create HTTP client for %q: %w
• cannot get API config: %w
• missing server url
• URL %s scheme must be 'http' or 'https'

AI-assisted analysis of VictoriaMetrics/VictoriaMetrics@5079fb58f1 (2026-09-03). Data as JSON: /api/errors/4c74e06eb4b854a1. Report an issue: GitHub.