cayleygraph/cayley · error

cannot unnest more than one object on %q; use (%s: 1) to for

Error message

cannot unnest more than one object on %q; use (%s: 1) to force

What it means

When a nested object field is marked unnested (f2.UnNest), iterateObject inlines its single result row into the parent object; if the nested query produced more than one result, inlining is ambiguous, so the error asks the query author to add an explicit limit of 1 (using the LimitKey) to force unnesting.

Source

Thrown at query/graphql/graphql.go:375

			p2 := path.StartPathNodes(qs, r.id)
			if len(f2.Labels) != 0 {
				p2 = p2.LabelContext(f2.Labels)
			}
			if f2.Rev {
				p2 = p2.In(f2.Via)
			} else {
				p2 = p2.Out(f2.Via)
			}
			if len(f2.Labels) != 0 {
				p2 = p2.LabelContext()
			}
			arr, err := iterateObject(ctx, qs, &f2, p2)
			if err != nil {
				return out, err
			}
			if f2.UnNest {
				if len(arr) > 1 {
					return nil, fmt.Errorf("cannot unnest more than one object on %q; use (%s: 1) to force",
						f2.Alias, LimitKey)
				} else if len(arr) == 0 {
					continue
				}
				for k, v := range arr[0] {
					obj[k] = v
				}
			} else {
				var v interface{}
				if len(arr) == 1 {
					v = arr[0]
				} else if len(arr) > 1 {
					v = arr
				}
				obj[f2.Alias] = v
			}
		}
		out = append(out, obj)

View on GitHub (pinned to 81dcd7d73e)

Solutions

1. Add the limit directive to the nested field: (id: 1) style — i.e. set LimitKey to 1 — to force unnesting.
2. Nest the field instead of unnesting so all results are returned as a list.
3. Tighten the nested query's constraints (has filters) so it matches at most one object.

Example fix

// before
user { friends @unnest { name } }
// after
user { friends(limit: 1) @unnest { name } }

const nested = field.nested; if (nested.unnest && !nested.limit) console.warn('unnested field may match multiple objects; add limit: 1');

out, err := iterateObject(ctx, qs, &f2, p2)
if err != nil && strings.Contains(err.Error(), "cannot unnest more than one object") { /* add LimitKey=1 or keep nesting */ }

When it happens

Trigger: A GraphQL query with an unnested nested field whose sub-query matches multiple nodes — e.g. unnesting a multi-valued relation without a limit — hitting query/graphql/graphql.go:375 when len(arr) > 1.

Common situations: Unnesting fields like friends/children that naturally return many results, or data changes causing a previously-single result to expand into multiple after new nodes are added.

Related errors

• unexpected arguments: %v (%d)
• unexpected value type for %v: %T
• must specify a tag name when saving a path
• invalid argument type in filter()
• must execute a Step

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