dgraph-io/dgraph · error

variable $%s is missing in given context.

Error message

variable $%s is missing in given context.

What it means

When an argument is supplied as a GraphQL variable (ast.Variable), matchArgSignature looks up the variable's type in the map of variable definitions collected from the operation (givenVarTypes). If the variable used in an argument value was never declared in the operation's variable definitions, this error is thrown. It catches variables that are referenced but never declared, which would otherwise fail at execution time on the remote.

Source

Thrown at graphql/schema/remote.go:426

// matchArgSignature matches the type signature for arguments supplied in metadata with
// corresponding remote arguments
func matchArgSignature(md *argMatchingMetadata) error {
	// TODO: maybe add path information in error messages,
	// so they are more informative. Like if query was `query { userNames(car: {age: $var}) }`,
	// then for errors on `age`, we shouldn't just be putting `age` in error messages,
	// instead we should put `car.age`
	for givenArgName, givenArgVal := range md.givenArgVals {
		remoteArgTyp, ok := md.remoteArgMd.typMap[givenArgName]
		if !ok {
			return errors.Errorf("argument `%s` is not present in remote %s `%s`.",
				givenArgName, *md.operationType, *md.givenQryName)
		}

		switch givenArgVal.Kind {
		case ast.Variable:
			givenArgTyp, ok := md.givenVarTypes[givenArgVal.Raw]
			if !ok {
				return errors.Errorf("variable $%s is missing in given context.", givenArgVal.Raw)
			}
			// TODO: we will consider ID as String for the purpose of type matching
			//rootType := givenArgTyp
			//for rootType.NamedType == "" {
			//	rootType = rootType.Elem
			//}
			//if rootType.NamedType == "ID" {
			//	rootType.NamedType = "String"
			//}
			expectedArgType := givenArgTyp.String()
			gotArgType := remoteArgTyp.String()
			if expectedArgType != gotArgType {
				return errors.Errorf("found type mismatch for variable `$%s` in %s `%s`, expected"+
					" `%s`, got `%s`.", givenArgVal.Raw, *md.operationType, *md.givenQryName,
					expectedArgType, gotArgType)
			}
			// deep check the remote type and verify it with the local schema.
			if err := matchDeepTypes(remoteArgTyp, md.remoteTypes, md.schema); err != nil {

View on GitHub (pinned to 759e242be6)

Solutions

  1. Add a variable definition to the operation: `query MyQuery($var: Int!) { ... }` matching where $var is used.
  2. Fix typos so the variable usage and declaration names match exactly (including $ prefix handling).
  3. If the value should be a literal instead, inline the scalar value rather than using a variable.
  4. Regenerate queries from templates so variable declarations and usages are emitted together.

Example fix

// before
query { userNames(car: {age: $var}) }
// after
query($var: Int!) { userNames(car: {age: $var}) }
Defensive patterns

Strategy: validation

Validate before calling

// Parse the operation and ensure every $var used has a definition
for _, v := range collectUsedVariables(queryAST) {
    if _, ok := varDefinitions[v]; !ok {
        return fmt.Errorf("variable $%s used but not declared", v)
    }
}

Try / catch

if err := validateRemoteGraphql(...); err != nil {
    if strings.Contains(err.Error(), "is missing in given context") {
        return fmt.Errorf("undeclared variable in query: %w", err)
    }
    return err
}

Prevention

When it happens

Trigger: validateRemoteGraphql -> matchArgSignature on a query like `query { userNames(car: {age: $var}) }` where `$var` is used but there is no `($var: Int!)` variable definition on the operation, including nested object/list argument values.

Common situations: Copy-pasting a query fragment and losing the variable declaration line; dynamically building queries and appending variable usages without variable definitions; typo in variable name between usage and declaration ($userId vs $id).

Related errors

AI-assisted analysis of dgraph-io/dgraph@759e242be6 (2026-09-01). Data as JSON: /api/errors/faec2a1070c91b49. Report an issue: GitHub.