cayleygraph/cayley · error

label directive should have 'v' argument

Error message

label directive should have 'v' argument

What it means

When @label has exactly one argument, that argument must be named `v`. Any other argument name (or an unnamed/positional-looking argument) triggers this error.

Source

Thrown at query/graphql/graphql.go:518

	if fld.Alias != nil && fld.Alias.Value != "" {
		out.Alias = fld.Alias.Value
	} else {
		out.Alias = name
	}
	out.Via, out.Rev = stringToVia(name)
	// first check for "label" directive - it will affect all traversals
	for _, d := range fld.Directives {
		if d.Name == nil {
			continue
		}
		switch d.Name.Value {
		case "label":
			if len(d.Arguments) == 0 {
				out.Labels = nil
			} else if len(d.Arguments) > 1 {
				return out, fmt.Errorf("label directive should have 0 or 1 argument")
			} else if a := d.Arguments[0]; a.Name == nil || a.Name.Value != "v" {
				return out, fmt.Errorf("label directive should have 'v' argument")
			} else {
				vals, err := convValue(a.Value)
				if err != nil {
					return out, fmt.Errorf("error parsing label: %v", err)
				}
				out.Labels = vals
			}
		}
	}
	for _, d := range fld.Directives {
		if d.Name == nil {
			continue
		}
		switch d.Name.Value {
		case "rev", "reverse":
			if len(d.Arguments) == 0 {
				out.Rev = out.Rev != true
			} else {

View on GitHub (pinned to 81dcd7d73e)

Solutions

1. Rename the argument to `v`: `@label(v: "value")`
2. Check the directive's documented signature and follow it
3. Omit arguments entirely (`@label`) to clear labels

Example fix

// before
q := "query { node @label(val: "x") { id } }"
// after
q := "query { node @label(v: "x") { id } }"

function validateLabelArg(d) {
  if (d.arguments.length === 1 && d.arguments[0].name?.value !== 'v') {
    throw new Error('@label argument must be named v');
  }
}

const isNamedV = (a) => a?.name?.value === 'v';

When it happens

Trigger: A directive like `@label(label: "x")` or `@label("x")` parsed to an argument whose Name is nil or != "v" in convField.

Common situations: Renaming the argument for clarity; translating examples from other GraphQL dialects; typos like `@label(val: "x")`.

Understand the failure class

Background: "must be a positive integer", "cannot be empty", "invalid argument": how invalid-argument errors work across open-source libraries — this error's family across 33 libraries.

Related errors

• label directive should have 0 or 1 argument
• error parsing label: %v
• node tokens not valid
• unexpected arguments: %v (%d)
• unexpected value type for %v: %T

AI-assisted analysis of cayleygraph/cayley@81dcd7d73e (2026-09-06). Data as JSON: /api/errors/2bbd87019ee56047. Report an issue: GitHub.