found type mismatch for variable `$%s` in %s `%s`, expected

Error message

found type mismatch for variable `$%s` in %s `%s`, expected `%s`, got `%s`.

What it means

For a variable argument, matchArgSignature compares the declared variable type (expected, from the operation's variable definitions) with the remote argument's type (got). If their type strings differ — including wrappers like NonNull or List — this error is thrown. It ensures the client-declared variable type is assignable to what the remote operation actually accepts.

Source

Thrown at graphql/schema/remote.go:439

		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 {
				return err
			}
		case ast.ObjectValue:
			if !(remoteArgTyp.Kind == inputObject || (remoteArgTyp.
				Kind == nonNull && remoteArgTyp.OfType != nil && remoteArgTyp.OfType.
				Kind == inputObject)) {
				return errors.Errorf("object value supplied for argument `%s` in %s `%s`, "+
					"but remote argument doesn't accept INPUT_OBJECT.", givenArgName,
					*md.operationType, *md.givenQryName)
			}
			remoteObjTypname := remoteArgTyp.NamedType()
			remoteObjTyp, ok := md.remoteTypes[remoteObjTypname]
			if !ok {

View on GitHub (pinned to 759e242be6)

Solutions

Change the variable declaration type to exactly match the remote argument type string (including [] and ! wrappers).
Introspect the remote field's arguments and copy the type verbatim into the variable definition.
If the remote changed nullability recently, update stored queries or pin the remote schema version.
Note the library intentionally treats ID as String in places (see commented TODO); if you rely on that, ensure the named types align otherwise.

Example fix

// before
query($age: String) { userNames(car: {age: $age}) }
// remote arg: age: Int!
// after
query($age: Int!) { userNames(car: {age: $age}) }

Defensive patterns

Strategy: validation

Validate before calling

// Compare declared variable type to remote arg type before composing
if varType.String() != remoteArgType.String() {
    return fmt.Errorf("$%s: %s != remote %s", varName, varType, remoteArgType)
}

Type guard

func variableTypeMatches(declared, remote string) bool { return declared == remote }

Try / catch

if err := validateRemoteGraphql(...); err != nil {
    if strings.Contains(err.Error(), "found type mismatch for variable") {
        return fmt.Errorf("fix variable declaration: %w", err)
    }
    return err
}

Prevention

Copy variable types verbatim from remote introspection
Include [] and ! wrappers when declaring variables
Re-validate queries after upstream schema changes
Treat ID arguments carefully (String vs ID)

When it happens

Trigger: validateRemoteGraphql -> matchArgSignature when e.g. the operation declares `$var: String` but the remote argument is `Int`, or declares `[Int]` where the remote expects `Int`, or omits the `!` the remote requires (and vice versa).

Common situations: Remote API tightened nullability (Int -> Int!) after upgrade; client template uses a generic String variable for IDs/numbers; list vs single-value mismatch; ID vs String mismatch where the library did not apply its ID-as-String leniency.

Related errors

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