What causes "Expected a non-null value but received null" in hasura/graphql-engine?

Remove the explicit null from the metadata

hasura/graphql-engine · error · TypecheckError

Expected a non-null value but received null

Error message

Expected a non-null value but received null

What it means

TypecheckError variant raised when a null JSON value is typechecked against a non-nullable type. It signals that the metadata explicitly contains null where the declared type disallows it (distinct from a missing key, which is handled elsewhere).

Source

Thrown at v3/crates/metadata-resolve/src/helpers/typecheck.rs:23

use crate::types::error::ShouldBeAnError;
use crate::{Qualified, QualifiedBaseType, QualifiedTypeName, QualifiedTypeReference};
use open_dds::flags::Flag;
use open_dds::types::{CustomTypeName, FieldName};
use thiserror::Error;

#[derive(Error, Debug, PartialEq)]
/// Errors that can occur when typechecking a value
pub enum TypecheckError {
    #[error("Expected a value of type {expected:} but got value {actual:}")]
    ScalarTypeMismatch {
        expected: open_dds::types::InbuiltType,
        actual: serde_json::Value,
    },
    #[error("Error in array item: {inner_error:}")]
    ArrayItemMismatch { inner_error: Box<TypecheckError> },
    #[error("Expected an array but instead got value {value:}")]
    NonArrayValue { value: serde_json::Value },
    #[error("Expected a non-null value but received null")]
    NullInNonNullableColumn,
}

#[derive(Error, Debug, PartialEq)]
/// Issues that can occur when typechecking a value against an object type
pub enum TypecheckIssue {
    #[error("Expected an object value of type {expected:} but got value {actual:}")]
    ObjectTypeMismatch {
        expected: Qualified<CustomTypeName>,
        actual: serde_json::Value,
    },

    #[error("Typecheck failed for field {field_name:} in object type {object_type:}: {error:}")]
    ObjectTypeField {
        field_name: FieldName,
        object_type: Qualified<CustomTypeName>,
        error: TypecheckError,
    },

View on GitHub (pinned to 724551b9ae)

Solutions

Remove the explicit null from the metadata
Make the target type nullable if null is a legitimate value
For arrays, ensure element type is nullable ([Int!]) before allowing null items

Example fix

// before
field:
  type: Int!
  default: null

// after
field:
  type: Int!
  default: 0

Defensive patterns

Strategy: validation

Validate before calling

fn reject_null_in_non_nullable(v: &serde_json::Value, nullable: bool) -> Result<(), String> {
    if !nullable && v.is_null() {
        Err("null value in non-nullable position".into())
    } else {
        Ok(())
    }
}

Try / catch

if let TypecheckError::NullInNonNullableColumn = err {
    eprintln!("remove the explicit null or make the type nullable");
}

Prevention

Never write default: null explicitly; omit the key instead
Audit generated metadata for stray nulls
Make element types nullable ([Int!]) before allowing null items

When it happens

Trigger: Writing default: null or an explicit null element/field in metadata for a non-nullable argument, field, or array element (e.g. [Int!] contains a null item).

Common situations: Explicit nulls left over from templated/generated metadata, optional fields converted to non-optional without cleaning nulls, nulls inside arrays typed as non-null element lists.

Related errors

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/31a51e65d798724d. Report an issue: GitHub.