In GraphQL, why does adding a non-null argument with no default break existing documents?

## The rule that does the breaking GraphQL's validation rules include one about required arguments: for every field and directive in a document, any argument whose type is non-null **and which declares no default value** must be present, and its value must not be the literal `null`. That single rule is the whole mechanism. The moment the schema declares such an argument, every document that selects the field without supplying it is invalid — not deprecated, not degraded, invalid. The blast radius surprises people because it has nothing to do with intent. Consider a clinical-trial registry: ```graphql type Query { trialsBySite(siteId: ID!): [Trial!]! } ``` Add `protocolVersion: String!` to it and a deployed document like ```graphql query SiteTrials($siteId: ID!) { trialsBySite(siteId: $siteId) { id phase } } ``` stops validating. The team that owns that document never asked for `protocolVersion` and may not know it exists. They are broken anyway, because the requirement is attached to the *field*, and selecting the field is the only thing they did. ## Non-null is not the same as required The rule turns on two conditions, and the second is the escape hatch. An argument declared `String!` with a default value is non-null but **not required**: the document may omit it, and the server substitutes the default during argument coercion. So ```graphql type Query { trialsBySite(siteId: ID!, protocolVersion: String! = "v3"): [Trial!]! } ``` is a safe addition, while the same argument without `= "v3"` is not. Candidates who have internalised "non-null means the client must send it" get this backwards; the question is always whether a default exists to stand in. The other safe shape is simply a nullable argument, `protocolVersion: String`, which the server then has to handle as absent. Which of the two you pick is a modelling decision — a default says "there is a sensible value", nullable says "absence is meaningful" — but both preserve every deployed document. ## Where the failure lands Validation runs before execution, so nothing resolves at all. The response has no partial data: an `errors` entry describing the missing argument, and `data` absent entirely. That is important operationally, because it means the failure is total per request rather than confined to one branch of the response. A screen that happened to select the affected field alongside eleven healthy fields shows nothing, not eleven-twelfths of itself. It also means the failure is *deterministic and instant*. There is no window in which some requests work. The first request sent after the schema is deployed fails, from every client, whether or not that client has redeployed. ## The input-object version of the same trap The same class of edit exists one level down. Adding a non-null field with no default to an input object type — say `consentVersion: String!` on `EnrollParticipantInput` — breaks every caller that constructs that input. There are two paths to the failure and both end in a rejected request: * When the input is written as a **literal** in the document, a validation rule about required input-object fields rejects it, exactly as with arguments. * When the input arrives through **variables**, the document itself is fine — it just says `$input: EnrollParticipantInput!`. The failure happens during variable coercion, before execution, and surfaces as a request error rather than a field error. That difference matters when you are reading an incident report: the same schema edit produces two different error messages depending on how the caller happened to build its input, and neither one names your new field in the client's own source. ## The subtler variable rule There is a related rule people meet less often. A document may pass a *nullable* variable into a non-null argument only when the variable declares a non-null default value, or the argument location itself has a default. So a client that dutifully starts sending the new argument, but declares it as `$protocolVersion: String` rather than `String!`, still fails validation. When someone reports "I added the argument and it still doesn't work", this is usually why. ## What to do instead If the argument genuinely must be mandatory for new behaviour, give it a default value that reproduces the old behaviour, or make it nullable and treat absence as the old behaviour. If neither is honest — the field simply cannot be answered without the new input — then the new requirement is a new field, not an edit to the old one, and the old field's retirement becomes a separate decision with its own timeline.