diff --git a/website/src/docs/hotchocolate/v16/api-reference/apollo-federation.md b/website/src/docs/hotchocolate/v16/api-reference/apollo-federation.md index 9fbbce89ed6..d810aedf9f8 100644 --- a/website/src/docs/hotchocolate/v16/api-reference/apollo-federation.md +++ b/website/src/docs/hotchocolate/v16/api-reference/apollo-federation.md @@ -414,17 +414,6 @@ query { For creating a supergraph, see the [Apollo Router documentation](https://www.apollographql.com/docs/router/quickstart/) or [`@apollo/gateway` documentation](https://www.npmjs.com/package/@apollo/gateway). -# Troubleshooting - -**"\_entities" query returns null for a representation** -Verify that the `__typename` value matches the GraphQL type name exactly and that the key field names and types match the entity definition. - -**Reference resolver parameter mismatch** -The parameter name in the reference resolver must match the GraphQL field name (not the C# property name). For example, if the GraphQL field is `id`, the parameter must be `string id`. - -**Entity type name does not match across subgraphs** -Use `[GraphQLName("...")]` or `descriptor.Name("...")` to set the GraphQL name explicitly if the C# class names differ. - # Next Steps - [Resolvers](/docs/hotchocolate/v16/resolvers-and-data/resolvers) for resolver patterns diff --git a/website/src/docs/hotchocolate/v16/api-reference/custom-attributes.md b/website/src/docs/hotchocolate/v16/api-reference/custom-attributes.md index 9c76008e113..6fcf8c5839a 100644 --- a/website/src/docs/hotchocolate/v16/api-reference/custom-attributes.md +++ b/website/src/docs/hotchocolate/v16/api-reference/custom-attributes.md @@ -200,17 +200,6 @@ public sealed class MyCustomAttribute : DescriptorAttribute } ``` -# Troubleshooting - -**Attribute does not appear to have any effect** -Verify that the attribute is in the correct namespace and that the NuGet package is installed. Some attributes (like `[UseFiltering]`) require additional packages such as `HotChocolate.Data`. - -**Middleware attribute ordering is wrong** -Attribute order in C# is not guaranteed. Middleware attributes use `[CallerLineNumber]` to infer order. Place attributes on separate lines with the correct top-to-bottom order: `[UsePaging]`, `[UseProjection]`, `[UseFiltering]`, `[UseSorting]`. - -**Custom attribute not being applied** -Confirm that you are inheriting from the correct base class and that the `OnConfigure` method calls the expected descriptor methods. - # Next Steps - [Building a schema](/docs/hotchocolate/v16/building-a-schema) for type system configuration diff --git a/website/src/docs/hotchocolate/v16/api-reference/errors.md b/website/src/docs/hotchocolate/v16/api-reference/errors.md index e2864b5a7f7..3cebc941584 100644 --- a/website/src/docs/hotchocolate/v16/api-reference/errors.md +++ b/website/src/docs/hotchocolate/v16/api-reference/errors.md @@ -75,17 +75,6 @@ builder > Do not enable `IncludeExceptionDetails` in production. Exception details can leak security-sensitive information. -# Troubleshooting - -**"Unexpected Execution Error" with no details** -Register an `IErrorFilter` to translate exceptions into meaningful GraphQL errors. Alternatively, enable `IncludeExceptionDetails` during development to see the full exception. - -**Error filter not being invoked** -Verify that you registered the filter using `AddErrorFilter()` on `IServiceCollection`. If you are using the split service provider model in v16, you may need to register the filter's dependencies using `AddApplicationService()` on the `IRequestExecutorBuilder`. - -**ReportError does not appear in the response** -Confirm that the resolver continues to execute after calling `ReportError`. Non-terminating errors require the resolver to return a value (or `null`). - # Next Steps - [Mutation conventions](/docs/hotchocolate/v16/building-a-schema/mutations) for structured mutation error handling diff --git a/website/src/docs/hotchocolate/v16/api-reference/executable.md b/website/src/docs/hotchocolate/v16/api-reference/executable.md index 9a99babdc13..03e98ae3c87 100644 --- a/website/src/docs/hotchocolate/v16/api-reference/executable.md +++ b/website/src/docs/hotchocolate/v16/api-reference/executable.md @@ -113,14 +113,6 @@ public class EntityFrameworkExecutable : QueryableExecutable } ``` -# Troubleshooting - -**Executable returns all items instead of applying filters** -Verify that you registered the correct filtering provider for your database (e.g., `AddMongoDbFiltering()` for MongoDB). The `IExecutable` must be paired with the appropriate data middleware. - -**"Sequence contains more than one element" exception** -This occurs when `SingleOrDefaultAsync` finds multiple results. Verify that your query criteria produce a unique result, or use `FirstOrDefaultAsync` instead. - # Next Steps - [Entity Framework integration](/docs/hotchocolate/v16/integrations/entity-framework) for EF Core executables diff --git a/website/src/docs/hotchocolate/v16/api-reference/extending-filtering.md b/website/src/docs/hotchocolate/v16/api-reference/extending-filtering.md index 5993e2cc6a7..3d06a2d6ff8 100644 --- a/website/src/docs/hotchocolate/v16/api-reference/extending-filtering.md +++ b/website/src/docs/hotchocolate/v16/api-reference/extending-filtering.md @@ -285,17 +285,6 @@ builder.Services y => y.AddFieldHandler())))); ``` -# Troubleshooting - -**Custom handler is not invoked** -Verify that your handler's `CanHandle` method returns `true` for the expected field. Handlers are checked in registration order, and the first match wins. - -**Filter operations not appearing in the schema** -Confirm that you registered the operation on the convention descriptor and that the operation is applied to the correct `FilterInputType` using the `Configure` method. - -**"Provider not found" errors** -Ensure that the convention and provider are registered on the schema builder. If you are using scoped conventions, verify the scope matches between the registration and the attribute. - # Next Steps - [Filtering](/docs/hotchocolate/v16/resolvers-and-data/filtering) for using built-in filtering diff --git a/website/src/docs/hotchocolate/v16/api-reference/language.md b/website/src/docs/hotchocolate/v16/api-reference/language.md index 5531693d8be..24eea4c390e 100644 --- a/website/src/docs/hotchocolate/v16/api-reference/language.md +++ b/website/src/docs/hotchocolate/v16/api-reference/language.md @@ -85,14 +85,6 @@ The interface defines the `NodeKind` of the node. | InputObjectTypeExtension | [Input type extension](https://spec.graphql.org/June2018/#sec-Input-Object-Extensions) | Schema | input foo {} | | DirectiveDefinition | [Directive definition](https://spec.graphql.org/June2018/#sec-Type-System.Directives) | Schema | directive @foo on | -# Troubleshooting - -**Syntax node prints unexpected output** -Call `ToString()` on the node to see its GraphQL representation. Compare this with the original input to identify discrepancies. - -**Custom syntax node not recognized** -Hot Chocolate uses a fixed set of node kinds. If you need custom nodes, work with the existing node types and use the extension data properties to attach metadata. - # Next Steps - [Visitors](/docs/hotchocolate/v16/api-reference/visitors) for traversing the AST diff --git a/website/src/docs/hotchocolate/v16/api-reference/options.md b/website/src/docs/hotchocolate/v16/api-reference/options.md index 9f1a864fb18..e7382f53b7f 100644 --- a/website/src/docs/hotchocolate/v16/api-reference/options.md +++ b/website/src/docs/hotchocolate/v16/api-reference/options.md @@ -262,17 +262,6 @@ builder.Services | `DefaultScope` | `CacheControlScope` | `Public` | The default cache scope applied to fields when `ApplyDefaults` is `true`. Values: `Public`, `Private`. | | `ApplyDefaults` | `bool` | `true` | When `true`, applies `DefaultMaxAge` and `DefaultScope` to all fields that do not already have a `@cacheControl` directive, are on the Query root type, or are responsible for fetching data. | -# Troubleshooting - -**Options changes do not take effect** -Verify that you are calling the correct `Modify*` method. For example, `ModifyOptions` modifies schema options, while `ModifyRequestOptions` modifies execution options. These are separate configuration APIs. - -**Execution timeout errors in development** -When the debugger is attached, the default timeout is 30 minutes. In production, it defaults to 30 seconds. You can override it with `ModifyRequestOptions(o => o.ExecutionTimeout = TimeSpan.FromSeconds(60))`. - -**Batching returns an error** -Batching is disabled by default in v16. Enable it with `ModifyServerOptions(o => o.Batching = AllowedBatching.All)`. - # Next Steps - [Execution engine](/docs/hotchocolate/v16/execution-engine) for pipeline configuration diff --git a/website/src/docs/hotchocolate/v16/api-reference/visitors.md b/website/src/docs/hotchocolate/v16/api-reference/visitors.md index b8dfb528b1f..a942c76d2eb 100644 --- a/website/src/docs/hotchocolate/v16/api-reference/visitors.md +++ b/website/src/docs/hotchocolate/v16/api-reference/visitors.md @@ -140,14 +140,6 @@ query { } ``` -# Troubleshooting - -**Visitor does not enter child nodes** -Verify that the `Enter` method returns `Continue`. Returning `Skip` or `Break` prevents traversal of child nodes. - -**State is lost between nodes** -The `SyntaxWalker` is stateless. All state must be stored on the `TContext` object. Verify that you push and pop state correctly in `OnBeforeEnter` and `OnAfterLeave`. - # Next Steps - [Language reference](/docs/hotchocolate/v16/api-reference/language) for AST node types diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/arguments.md b/website/src/docs/hotchocolate/v16/building-a-schema/arguments.md index 7cdeec7d92c..86bb6faa076 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/arguments.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/arguments.md @@ -206,20 +206,6 @@ type Query { } ``` -# Troubleshooting - -## Argument not appearing in schema - -Verify the parameter is `public` and is not a type that Hot Chocolate recognizes as a service (like `CancellationToken`, `ClaimsPrincipal`, or types registered in DI). Service types are injected but not exposed as arguments. - -## Wrong nullability on argument - -Check whether nullable reference types are enabled in your project. With NRT enabled, `string` is non-null and `string?` is nullable. Without NRT, all reference types default to nullable. See [Non-Null](/docs/hotchocolate/v16/defining-a-schema/non-null). - -## ID deserialization fails - -If a global ID cannot be deserialized, the error message indicates a type mismatch. Verify that the `[ID]` type name matches the type that serialized the ID. If using `[ID(nameof(Product))]`, the ID must have been serialized for the `Product` type. - # Next Steps - **Need structured input?** See [Input Object Types](/docs/hotchocolate/v16/defining-a-schema/input-object-types). diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/directives.md b/website/src/docs/hotchocolate/v16/building-a-schema/directives.md index bf58bfc895e..d3f464551c1 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/directives.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/directives.md @@ -207,20 +207,6 @@ type Bar @a @b { The directive middleware executes in order: `a`, `b`, `c`, `d`, `e`, `f`. Object-level directives run first, followed by field-definition directives, followed by query directives. -# Troubleshooting - -## Directive not recognized in query - -Verify the directive is registered with `.AddDirectiveType()` and that its location includes executable locations (like `FIELD`). Type-system directives cannot be used in client queries. - -## Middleware not executing - -Confirm the directive location matches where it is applied. A directive with `DirectiveLocation.Object` does not fire when applied to a field in a query. - -## Duplicate directive error - -If a non-repeatable directive is applied twice at the same location, validation fails. Either mark the directive as `.Repeatable()` or apply it only once. - # Next Steps - **Need to deprecate fields?** See [Versioning](/docs/hotchocolate/v16/defining-a-schema/versioning). diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/documentation.md b/website/src/docs/hotchocolate/v16/building-a-schema/documentation.md index 83f05d4201d..161ea32d0a0 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/documentation.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/documentation.md @@ -198,20 +198,6 @@ builder.Services ?? new NoOpStringBuilderPool()))); ``` -# Troubleshooting - -## Descriptions not appearing in schema - -Verify that `GenerateDocumentationFile` is set to `true` in your `.csproj`. Without this, the XML file is not generated and Hot Chocolate has no documentation to read. - -## XML docs overridden by empty attribute - -In implementation-first, `[GraphQLDescription]` with an empty or null value falls back to XML documentation. In code-first, `Description("")` takes precedence and produces an empty description. Remove the explicit `Description()` call to let XML docs take effect. - -## Descriptions missing after adding custom naming convention - -When you register a custom `INamingConventions`, you must pass an `XmlDocumentationProvider` to the constructor. Without it, the convention cannot resolve XML documentation. - # Next Steps - **Need to deprecate fields?** See [Versioning](/docs/hotchocolate/v16/defining-a-schema/versioning). diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/dynamic-schemas.md b/website/src/docs/hotchocolate/v16/building-a-schema/dynamic-schemas.md index b00fd87f2c6..89e158b7cdf 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/dynamic-schemas.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/dynamic-schemas.md @@ -219,20 +219,6 @@ builder.Services .AddType(productType); ``` -# Troubleshooting - -## Schema not updating after TypesChanged - -Verify that the `TypesChanged` event is wired up and fired. The schema rebuild is asynchronous, so there may be a brief delay before the new schema is active. Check the logs for schema build errors. - -## CreateUnsafe produces validation errors - -`CreateUnsafe` bypasses the descriptor-level validation. If a type definition is incomplete (missing required fields, invalid type references), the error surfaces during schema construction. Verify all field definitions have valid type references and resolvers. - -## Dynamic types not visible in introspection - -Types created through `ITypeModule` must be registered as part of the schema. Verify that your module returns them from `CreateTypesAsync`. If a type is an extension, ensure the base type it extends exists in the schema. - # Next Steps - **Need to extend existing types?** See [Extending Types](/docs/hotchocolate/v16/defining-a-schema/extending-types). diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/enums.md b/website/src/docs/hotchocolate/v16/building-a-schema/enums.md index fe0084db49b..9d061fc87d4 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/enums.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/enums.md @@ -206,20 +206,6 @@ public class UserRoleType : EnumType This is useful when enum values come from configuration or a database rather than a compile-time C# enum. -# Troubleshooting - -## Enum value not recognized - -If a client sends a string like `"guest"` (lowercase) and the schema expects `GUEST`, the request fails validation. Verify the client is sending the exact `UPPER_SNAKE_CASE` value. - -## Duplicate enum type name - -If two C# enums produce the same GraphQL name, the schema fails to build. Use `[GraphQLName]` on one of the enums to disambiguate. - -## Code-first enum not applied - -If you are using `EnumType` and the enum does not appear in the schema, verify you have registered it with `.AddType()`. Code-first enums require explicit registration. - # Next Steps - **Need to define output types?** See [Object Types](/docs/hotchocolate/v16/defining-a-schema/object-types). diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/extending-types.md b/website/src/docs/hotchocolate/v16/building-a-schema/extending-types.md index e0ec6d5925c..82837c08061 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/extending-types.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/extending-types.md @@ -278,24 +278,6 @@ public class PostExtensions The extension applies to every object type that implements `IPost`, not to the interface type itself. -# Troubleshooting - -## Extension not applied - -Verify you have registered the extension with `.AddTypeExtension()`. Unlike regular types, extensions require explicit registration. - -## Source generator extension not discovered - -When using `[ExtendObjectType]` with the source generator, the class must be `partial`. The source generator cannot extend non-partial classes. - -## Conflicting field names - -If an extension adds a field that already exists on the type, the schema fails to build. Either remove the duplicate field or use `[BindMember]` to replace the existing one. - -## Extension across assemblies - -Type extensions work across assembly boundaries. The assembly containing the extension must reference the assembly containing the original type and must use the Hot Chocolate source generator. Register the extension types in the main project's service configuration. - # Next Steps - **Need to define root types?** See [Queries](/docs/hotchocolate/v16/defining-a-schema/queries) and [Mutations](/docs/hotchocolate/v16/defining-a-schema/mutations). diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/input-object-types.md b/website/src/docs/hotchocolate/v16/building-a-schema/input-object-types.md index 9fba3353bc2..d468e72bd83 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/input-object-types.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/input-object-types.md @@ -259,20 +259,6 @@ public class PetInputType : InputObjectType All fields on a `@oneOf` input must be nullable. Hot Chocolate validates at runtime that exactly one field is provided. -# Troubleshooting - -## Input type not appearing in schema - -Verify the class is used as a parameter in a resolver. If the class is not referenced by any resolver, Hot Chocolate does not include it in the schema. In code-first, register it explicitly with `.AddType()`. - -## Constructor validation error at startup - -If you use an immutable type and the constructor parameters do not match the properties, Hot Chocolate throws at schema build time. Verify that each parameter name matches a property name (case-insensitive first letter) and that types align. - -## `Optional` field still required - -When using `Optional` on a non-nullable type, add `[DefaultValue]` to make it optional in the schema. Without a default value, the field remains required. - # Next Steps - **Need scalar arguments?** See [Arguments](/docs/hotchocolate/v16/defining-a-schema/arguments). diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/interfaces.md b/website/src/docs/hotchocolate/v16/building-a-schema/interfaces.md index a9125078af8..af7a1599285 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/interfaces.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/interfaces.md @@ -318,20 +318,6 @@ builder.Services Register intermediate interfaces (like `DatedMessage`) explicitly if they are not returned directly from a resolver field. -# Troubleshooting - -## "Type is not registered" error - -Every type that implements an interface must be registered with `.AddType()`. Hot Chocolate cannot discover implementing types automatically. - -## Interface field not appearing on implementing type - -The implementing object type must declare the same fields as the interface. If a field is missing, the schema fails validation. Ensure the C# class includes properties matching all interface members. - -## Multiple interfaces with same field name - -If a type implements two interfaces that both declare a field with the same name and type, the field appears once on the implementing type. If the types differ, the schema fails to build. Rename one of the fields using `[GraphQLName]`. - # Next Steps - **Need types without shared fields?** See [Unions](/docs/hotchocolate/v16/defining-a-schema/unions). diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/lists.md b/website/src/docs/hotchocolate/v16/building-a-schema/lists.md index 936361574b1..d8464a2d505 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/lists.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/lists.md @@ -120,20 +120,6 @@ public static partial class GridQueries This produces `matrix: [[Int!]!]!` in the schema. -# Troubleshooting - -## List returns as single item - -If you expected a list but the schema shows a single object, verify that the resolver return type is a collection (like `List` or `T[]`). A single `T` return type produces a non-list field. - -## Null items in a non-null list - -If the list type is `[User!]!` but a null item appears at runtime, the execution engine raises an error and may null out the entire list or its parent. Either filter out nulls in the resolver or change the inner type to nullable (`List`). - -## IQueryable not executing - -When returning `IQueryable`, Hot Chocolate materializes the query. If you use EF Core, verify that the `DbContext` lifetime is scoped per request. Use `[UseDbContext]` or register the context with the appropriate lifetime. - # Next Steps - **Need to control nullability?** See [Non-Null](/docs/hotchocolate/v16/defining-a-schema/non-null). diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/mutations.md b/website/src/docs/hotchocolate/v16/building-a-schema/mutations.md index ba8d476e732..c580ad09fdd 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/mutations.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/mutations.md @@ -406,20 +406,6 @@ builder.Services .AddTransactionScopeHandler(); ``` -# Troubleshooting - -## Input type not generated - -Verify that mutation conventions are enabled (`AddMutationConventions`). Without conventions, Hot Chocolate uses the method parameters directly as field arguments instead of wrapping them in an input type. - -## Domain error not appearing on payload - -Check that the exception type is annotated with `[Error(typeof(...))]` on the mutation method. Also verify mutation conventions are enabled. Domain errors require the convention's payload rewriting to work. - -## Multiple mutations execute out of order - -GraphQL guarantees serial execution of top-level mutation fields. If mutations appear to run out of order, verify that you are sending them as multiple fields in a single `mutation` operation, not as separate requests. - # Next Steps - **Need to read data?** See [Queries](/docs/hotchocolate/v16/defining-a-schema/queries). diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/non-null.md b/website/src/docs/hotchocolate/v16/building-a-schema/non-null.md index 458ba37107f..9e8af57527a 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/non-null.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/non-null.md @@ -151,20 +151,6 @@ public class BookType : ObjectType Both produce `genres: [String!]` in the schema. -# Troubleshooting - -## Field unexpectedly nullable - -Verify that NRT is enabled in your project. Without NRT, all reference type fields default to nullable. Check your `.csproj` for `enable`. - -## Resolver returns null for non-null field - -When a resolver returns `null` for a non-null field, the execution engine propagates the null up to the nearest nullable parent field. If no parent is nullable, the entire `data` response becomes `null`. Either make the field nullable in the schema or ensure the resolver always returns a value. - -## Input field nullability mismatch - -Input fields follow the same NRT rules. If a client sends `null` for a non-null input field, the request fails validation. Ensure your input classes accurately reflect which fields are optional. - # Next Steps - **Need to define lists?** See [Lists](/docs/hotchocolate/v16/defining-a-schema/lists). diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/object-types.md b/website/src/docs/hotchocolate/v16/building-a-schema/object-types.md index c06b0b9655c..c9225d08c81 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/object-types.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/object-types.md @@ -528,34 +528,6 @@ Clients query dictionary fields like any other list. This works with any key and value types. For example, `Dictionary` produces `KeyValuePairOfStringAndInt32` with the appropriate scalar types. -# Troubleshooting - -## Field not appearing in the schema - -Verify the property or method is `public`. Private, internal, and protected members are not exposed. If using code-first with explicit binding, confirm you have added the field with `descriptor.Field(...)`. - -## "Type is not registered" error - -In the code-first approach, `ObjectType` types must be registered with `.AddType()`. Unlike implementation-first types, they are not auto-discovered. - -```csharp -builder.Services - .AddGraphQLServer() - .AddType(); -``` - -## Nullable field shows as non-null (or vice versa) - -Check your project's nullable reference type settings. If `enable` is set in your `.csproj`, then `string` maps to `String!`. If nullable reference types are not enabled, `string` maps to `String` (nullable). See the [nullability table](#nullability) above. - -## Property returning null causes execution error - -If a field is non-null in the schema (for example, `String!`) but your resolver returns `null`, the execution engine raises an error. Either return a non-null value or change the C# type to nullable (e.g., `string?`). - -## Dictionary field generates unexpected type name - -Dictionary fields produce auto-generated type names like `KeyValuePairOfStringAndString`. You cannot rename the generated key-value pair type directly. If you need a custom name, define a dedicated class instead of using a dictionary. - # Next Steps - **Need to define query entry points?** See [Queries](/docs/hotchocolate/v16/defining-a-schema/queries). diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/queries.md b/website/src/docs/hotchocolate/v16/building-a-schema/queries.md index d40bbeabb8d..b8331e2ffc0 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/queries.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/queries.md @@ -168,20 +168,6 @@ You can override the generated name with `[GraphQLName]`: public static List GetBooks() => /* ... */; ``` -# Troubleshooting - -## "Root type class should be partial" (HC0091) - -The source generator requires `[QueryType]` classes to be `partial`. Add the `partial` keyword to the class declaration. - -## Field not appearing in the schema - -Verify the method is `public`. Private and internal methods are not exposed as fields. Also check that the class has the `[QueryType]` attribute and is `partial`. - -## Duplicate field name - -If two `[QueryType]` classes define methods that produce the same GraphQL field name, the schema fails to build. Rename one of the methods or use `[GraphQLName]` to disambiguate. - # Next Steps - **Need to write data?** See [Mutations](/docs/hotchocolate/v16/defining-a-schema/mutations). diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/relay.md b/website/src/docs/hotchocolate/v16/building-a-schema/relay.md index 762d6b4618e..a2a94932792 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/relay.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/relay.md @@ -377,24 +377,6 @@ builder.Services }); ``` -# Troubleshooting - -## "No type implements Node" - -At least one type must implement the `Node` interface when `AddGlobalObjectIdentification` is called. Annotate a type with `[Node]` or use `ImplementsNode()` in code-first. - -## Node resolver not found - -Hot Chocolate looks for a static method named `Get`, `GetAsync`, `Get{TypeName}`, or `Get{TypeName}Async`. If your method uses a different name, annotate it with `[NodeResolver]`. - -## Global ID deserialization fails - -If a client sends an ID that was serialized for a different type, deserialization fails with a type mismatch error. Verify the `[ID]` type name matches between the field that produced the ID and the argument that consumes it. - -## MaxAllowedNodeBatchSize - -In v16, `MaxAllowedNodeBatchSize` has moved from the `Node` type configuration to the `AddGlobalObjectIdentification` options. Pass it when calling `AddGlobalObjectIdentification(opts => opts.MaxAllowedNodeBatchSize = 50)`. - # Next Steps - **Need to fetch data efficiently?** See [DataLoader](/docs/hotchocolate/v16/resolvers-and-data/dataloader). diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/scalars.md b/website/src/docs/hotchocolate/v16/building-a-schema/scalars.md index a2e492383ed..86bce8f6a07 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/scalars.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/scalars.md @@ -36,38 +36,6 @@ Hot Chocolate automatically maps .NET types to GraphQL scalars. When you use a ` Hot Chocolate only exposes scalars that your schema uses. Unused scalars do not appear in the generated schema. -# Breaking Changes in v16 - -Several scalars have been renamed or replaced in v16. If you are upgrading from v15, review these changes. - -**Renamed scalars:** - -- `TimeSpan` is now `Duration` -- `Byte` (previously mapped to `byte`) is now `UnsignedByte`. The `Byte` scalar now maps to `sbyte`. - -**New scalars:** - -- `URI` replaces `URL` as the default scalar for `System.Uri` -- `Base64String` replaces the deprecated `ByteArray` scalar for `byte[]` -- `UnsignedShort`, `UnsignedInt`, and `UnsignedLong` support unsigned integer types - -**Removed scalars:** - -The following scalars from the `HotChocolate.Types.Scalars` package have been removed: - -- `NegativeFloat` -- `NonNegativeFloat` -- `NegativeInt` -- `NonPositiveInt` -- `NonNegativeInt` -- `NonEmptyString` - -If you relied on these for validation, define a [custom scalar](#custom-scalars) or use field middleware for validation instead. - -**Merged scalars:** - -- The `Json` scalar has been merged into `Any`. Use `Any` wherever you previously used `Json`. - # Built-in Spec Scalars ## String @@ -689,53 +657,6 @@ protected override LeafCoercionException FormatException(string runtimeValue) this); ``` -# Troubleshooting - -## Wrong scalar inferred for a field - -If a field uses a different scalar than expected, check the [mapping table](#net-type-to-graphql-scalar-mapping) for the default binding. You can override the inferred scalar with `[GraphQLType]`: - -```csharp -[GraphQLType] -public string GetExternalId() => Guid.NewGuid().ToString(); -``` - -Or bind a runtime type globally: - -```csharp -builder.Services - .AddGraphQLServer() - .BindRuntimeType(); -``` - -## "Cannot resolve scalar type" error - -Verify that the scalar type is registered. Built-in scalars are registered automatically, but custom scalars and NodaTime scalars require explicit registration with `.AddType()`. - -## Returning Dictionary from Any field throws an error - -Register the JSON type converter. The `Any` scalar uses `JsonElement` as its runtime type and cannot serialize dictionaries without it: - -```csharp -builder.Services - .AddGraphQLServer() - .AddJsonTypeConverter(); -``` - -## Scalar renamed after upgrading to v16 - -Check the [breaking changes](#breaking-changes-in-v16) section. Several scalars were renamed in v16 (`TimeSpan` to `Duration`, `Byte` to `UnsignedByte`). If clients depend on the old name, register the scalar explicitly with the old name by creating a custom type that inherits from the new scalar base class. - -## UUID format mismatch - -The `UUID` scalar defaults to the `D` format (`00000000-0000-0000-0000-000000000000`). If your clients expect a different format, register the scalar with the desired format specifier: - -```csharp -builder.Services - .AddGraphQLServer() - .AddType(new UuidType('N')); -``` - # Next Steps - **Need to define object types?** See [Object Types](/docs/hotchocolate/v16/building-a-schema/object-types). diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/subscriptions.md b/website/src/docs/hotchocolate/v16/building-a-schema/subscriptions.md index cd29bb01eb4..6d3ee667cd2 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/subscriptions.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/subscriptions.md @@ -383,28 +383,6 @@ type Subscription { Group your subscription classes by domain area, the same way you would split queries and mutations. -# Troubleshooting - -## Subscription field not appearing in the schema - -Verify the method has both the `[Subscribe]` attribute and a parameter marked with `[EventMessage]`. Both are required. Also check that the class has `[SubscriptionType]` and is `partial`. - -## Events published but subscribers receive nothing - -Make sure the topic string in `sender.SendAsync(topic, ...)` matches the subscription field. By default, the topic is the method name (e.g., `OnBookAdded`). Use `nameof(BookSubscriptions.OnBookAdded)` to keep them in sync. If you use `[Topic]`, ensure the topic string or pattern matches exactly. - -## WebSocket connection closes immediately - -Confirm that `app.UseWebSockets()` is called before `app.MapGraphQL()` in your middleware pipeline. Without the WebSocket middleware, the server cannot upgrade the connection. - -## "Only one subscription type can be registered" - -If you use code-first, only one class can be registered with `AddSubscriptionType()`. To split subscription fields across classes, switch to the source generator approach with `[SubscriptionType]` on multiple `partial` classes. - -## Events not shared across server instances - -The in-memory provider only delivers events within a single process. Switch to Redis, NATS, or Postgres for multi-instance deployments. - # Next Steps - **Need to read data?** See [Queries](/docs/hotchocolate/v16/defining-a-schema/queries). diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/unions.md b/website/src/docs/hotchocolate/v16/building-a-schema/unions.md index 02e391a12f3..3fc459c04d5 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/unions.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/unions.md @@ -122,20 +122,6 @@ Choose a union when the grouped types have no meaningful shared fields. Choose a | Query shared fields directly | No | Yes | | Types can belong to multiple | Yes | Yes | -# Troubleshooting - -## "No types registered for union" - -A union must contain at least one member type. Verify that you have registered each implementing class with `.AddType()` or included it in the `UnionType` configuration. - -## Unexpected `null` for union field - -If the resolver returns a type that is not part of the union, Hot Chocolate cannot resolve it and returns `null`. Verify the runtime type implements the marker interface or is listed in the union configuration. - -## Cannot query `__typename` on union - -The `__typename` meta-field is available on all union members. Clients can include `__typename` inside any inline fragment to determine which type was returned. - # Next Steps - **Need shared fields across types?** See [Interfaces](/docs/hotchocolate/v16/defining-a-schema/interfaces). diff --git a/website/src/docs/hotchocolate/v16/building-a-schema/versioning.md b/website/src/docs/hotchocolate/v16/building-a-schema/versioning.md index d0e44c0c4fb..58742f51f73 100644 --- a/website/src/docs/hotchocolate/v16/building-a-schema/versioning.md +++ b/website/src/docs/hotchocolate/v16/building-a-schema/versioning.md @@ -205,20 +205,6 @@ Consumers query feature stability through introspection: } ``` -# Troubleshooting - -## Deprecated field still returned in queries - -Deprecation does not remove a field. The field continues to work normally. Deprecation only marks it in introspection so tools can warn consumers. Remove the field from the schema when you are confident no consumers depend on it. - -## Opt-in field not visible in introspection - -Fields with `@requiresOptIn` are hidden by default. Use the `includeOptIn` argument in introspection queries to reveal them. Also verify that `EnableOptInFeatures = true` is set in your schema options. - -## Cannot deprecate required argument - -GraphQL does not allow deprecating a non-null argument without a default value. Add a default value to the argument first, then apply the deprecation. - # Next Steps - **Need to add descriptions?** See [Documentation](/docs/hotchocolate/v16/defining-a-schema/documentation). diff --git a/website/src/docs/hotchocolate/v16/execution-engine/field-middleware.md b/website/src/docs/hotchocolate/v16/execution-engine/field-middleware.md index d2cadf13ccd..3f5fdf20d45 100644 --- a/website/src/docs/hotchocolate/v16/execution-engine/field-middleware.md +++ b/website/src/docs/hotchocolate/v16/execution-engine/field-middleware.md @@ -282,17 +282,6 @@ descriptor }) ``` -# Troubleshooting - -**Middleware executes in an unexpected order** -Verify the declaration order. Middleware declared first runs first on the way down, but processes results last on the way back up. If you are using attributes, check the `Order` property or the line numbers. - -**Result is null after calling next(context)** -The field resolver may have returned `null`, or a preceding middleware may have set `Result` to `null`. Check whether all required data is available in the resolver. - -**Middleware pipeline validation error at startup** -Hot Chocolate validates the order of built-in data middleware (paging, filtering, sorting) by default. If you receive an ordering error, rearrange your middleware so that `UsePaging` is declared before `UseFiltering`, which is declared before `UseSorting`. - # Next Steps - [Execution engine overview](/docs/hotchocolate/v16/execution-engine) for request-level middleware diff --git a/website/src/docs/hotchocolate/v16/execution-engine/index.md b/website/src/docs/hotchocolate/v16/execution-engine/index.md index 60b3c8bffdf..dffa959ac46 100644 --- a/website/src/docs/hotchocolate/v16/execution-engine/index.md +++ b/website/src/docs/hotchocolate/v16/execution-engine/index.md @@ -202,17 +202,6 @@ Field middleware runs during field resolution, allowing you to add logic before The resolver compiler builds an optimized resolver pipeline for each field. You can customize it by providing parameter expression builders. -# Troubleshooting - -**Middleware not executing in the expected order** -Verify that you are using the correct `before` or `after` key. Print the pipeline at startup by inspecting the `RequestExecutorOptions.Pipeline` during configuration. - -**"The middleware with the key ... was not found" error** -The anchor key you specified in `before` or `after` does not exist in the pipeline. Check that the middleware you are referencing is registered and that the key matches a `WellKnownRequestMiddleware` constant. - -**Custom middleware runs but has no effect** -Confirm that you are calling `await next(context)` to continue the pipeline. If you do not call the next delegate, downstream middleware (including execution) will not run. - # Next Steps - [Field middleware](/docs/hotchocolate/v16/execution-engine/field-middleware) for per-field processing diff --git a/website/src/docs/hotchocolate/v16/get-started-with-graphql-in-net-core.md b/website/src/docs/hotchocolate/v16/get-started-with-graphql-in-net-core.md index 4133d8e2a23..b21d3a04b4c 100644 --- a/website/src/docs/hotchocolate/v16/get-started-with-graphql-in-net-core.md +++ b/website/src/docs/hotchocolate/v16/get-started-with-graphql-in-net-core.md @@ -175,20 +175,6 @@ You can browse the schema by clicking the **Schema** tab next to **Operation**. Your GraphQL server is running and responding to queries. -# Troubleshooting - -## Port already in use - -If `dotnet run` fails with an "address already in use" error, another process is using port 5095. Either stop that process or change the port in `Properties/launchSettings.json`. - -## Schema available does not appear in Nitro - -Verify the endpoint URL in Nitro matches the URL printed in the terminal output. If you changed the port, update the endpoint in Nitro accordingly. - -## Template not found - -If `dotnet new graphql` fails with "No templates matched the input template name", re-run `dotnet new install HotChocolate.Templates` and verify the installation succeeded. - # Next Steps - **"I want to learn about the type system."** See [Defining a Schema](/docs/hotchocolate/v16/defining-a-schema) for queries, mutations, subscriptions, and all the GraphQL types. diff --git a/website/src/docs/hotchocolate/v16/guides/dynamic-schemas.md b/website/src/docs/hotchocolate/v16/guides/dynamic-schemas.md index 8579b81ea53..9edc23fc802 100644 --- a/website/src/docs/hotchocolate/v16/guides/dynamic-schemas.md +++ b/website/src/docs/hotchocolate/v16/guides/dynamic-schemas.md @@ -219,20 +219,6 @@ builder.Services .AddType(productType); ``` -# Troubleshooting - -## Schema not updating after TypesChanged - -Verify that the `TypesChanged` event is wired up and fired. The schema rebuild is asynchronous, so there may be a brief delay before the new schema is active. Check the logs for schema build errors. - -## CreateUnsafe produces validation errors - -`CreateUnsafe` bypasses the descriptor-level validation. If a type definition is incomplete (missing required fields, invalid type references), the error surfaces during schema construction. Verify all field definitions have valid type references and resolvers. - -## Dynamic types not visible in introspection - -Types created through `ITypeModule` must be registered as part of the schema. Verify that your module returns them from `CreateTypesAsync`. If a type is an extension, ensure the base type it extends exists in the schema. - # Next Steps - **Extending existing types:** See [Extending Types](/docs/hotchocolate/v16/defining-a-schema/extending-types). diff --git a/website/src/docs/hotchocolate/v16/guides/error-handling.md b/website/src/docs/hotchocolate/v16/guides/error-handling.md index 0be9b87d6b8..aee564e3d2b 100644 --- a/website/src/docs/hotchocolate/v16/guides/error-handling.md +++ b/website/src/docs/hotchocolate/v16/guides/error-handling.md @@ -550,42 +550,6 @@ public class UserByEmailResultType : UnionType -# Troubleshooting - -## Exception messages not showing in responses - -By default, Hot Chocolate replaces exception messages with `"Unexpected Execution Error"` when no debugger is attached. This is a security measure. To see the original messages during development, enable `IncludeExceptionDetails`: - -```csharp -builder.Services - .AddGraphQLServer() - .ModifyRequestOptions(opt => opt.IncludeExceptionDetails = true); -``` - -In production, use an [error filter](#error-filters) to log the original exception and return a safe message to the client. - -## Error types not appearing in the schema - -Verify that mutation conventions are enabled. Domain errors on payloads require mutation conventions to rewrite the schema. - -```csharp -builder.Services - .AddGraphQLServer() - .AddMutationConventions(applyToAllMutations: true); -``` - -Also check that the `[Error(typeof(...))]` attribute is on the mutation method, not on the class. - -## AggregateException not unwrapping into multiple errors - -Hot Chocolate unwraps `AggregateException` automatically, but only for exception types declared with `[Error]` on the mutation. If an inner exception type is not declared, it is treated as a request error and appears in the top-level `errors` array instead. - -Make sure every exception type inside the `AggregateException` has a corresponding `[Error]` attribute on the mutation. - -## Error class missing required interface fields - -If you have a custom error interface (e.g., one that requires both `message` and `code`), every error class must expose matching properties. If a property is missing, schema generation fails. Check that each error class has all the properties defined by the interface. - # Next Steps - **Need mutation conventions?** See [Mutations](/docs/hotchocolate/v16/building-a-schema/mutations) for the full pattern including inputs, payloads, and naming customization. diff --git a/website/src/docs/hotchocolate/v16/guides/mcp-adapter.md b/website/src/docs/hotchocolate/v16/guides/mcp-adapter.md index 32b68df8316..1840ac21ea8 100644 --- a/website/src/docs/hotchocolate/v16/guides/mcp-adapter.md +++ b/website/src/docs/hotchocolate/v16/guides/mcp-adapter.md @@ -293,39 +293,6 @@ builder.Services When the Fusion gateway schema changes (for example, a new subgraph is composed), connected MCP clients receive tool list changed notifications automatically. -# Troubleshooting - -**"You must call AddMcp()" error when starting the application** - -You called `MapGraphQLMcp()` without registering the MCP services. Add `.AddMcp()` and `.AddMcpStorage()` to your GraphQL builder chain before calling `MapGraphQLMcp()`. - -**Tools do not appear in the MCP client** - -Verify that your `IMcpStorage` implementation returns the tool definitions from `GetOperationToolDefinitionsAsync`. If a tool's GraphQL operation references fields that do not exist on the schema, the adapter silently skips it and logs validation errors. Attach an `McpDiagnosticEventListener` to inspect validation errors: - -```csharp -builder.Services - .AddGraphQL() - .AddMcp() - .AddMcpStorage(myStorage) - .AddDiagnosticEventListener(_ => new MyMcpListener()); - -public class MyMcpListener : McpDiagnosticEventListener -{ - public override void ValidationErrors(IReadOnlyList errors) - { - foreach (var error in errors) - { - Console.WriteLine(error.Message); - } - } -} -``` - -**Tool list does not update after changing storage** - -Ensure your `IMcpStorage` implementation pushes events through the `IObservable` interface when definitions change. Without these events, connected MCP clients are not notified. - # Next Steps - [Error Handling](/docs/hotchocolate/v16/guides/error-handling) to customize how GraphQL errors appear in MCP tool results. diff --git a/website/src/docs/hotchocolate/v16/guides/openapi-adapter.md b/website/src/docs/hotchocolate/v16/guides/openapi-adapter.md index 68ce5f8b843..047b3610a6e 100644 --- a/website/src/docs/hotchocolate/v16/guides/openapi-adapter.md +++ b/website/src/docs/hotchocolate/v16/guides/openapi-adapter.md @@ -268,39 +268,6 @@ builder.Services The Fusion gateway composes schemas from multiple subgraphs. The OpenAPI adapter generates REST endpoints that execute operations against the composed schema, so a single REST endpoint can fetch data from multiple subgraphs transparently. -# Troubleshooting - -**Endpoint returns 404** - -Verify that your `IOpenApiDefinitionStorage` returns the definitions and that the route in the `@http` directive matches the URL you are requesting. Check that you called both `MapOpenApiEndpoints()` and `MapGraphQL()` in your endpoint configuration. If you added a definition at runtime, wait for the hot-reload cycle to complete. - -**Request body is not parsed** - -The adapter requires a `Content-Type: application/json` header on POST and PUT requests. Other content types are rejected. Ensure the `@body` directive is present on the variable that should receive the request body. - -**Endpoint returns 500 with validation errors** - -The operation references a field or type that does not exist on the GraphQL schema. The adapter validates definitions on startup and logs errors. Attach an `OpenApiDiagnosticEventListener` to inspect validation details: - -```csharp -builder.Services - .AddGraphQLServer() - .AddOpenApiDefinitionStorage(myStorage) - .AddDiagnosticEventListener(_ => new MyOpenApiListener()); - -public class MyOpenApiListener : OpenApiDiagnosticEventListener -{ - public override void ValidationErrors( - IReadOnlyList errors) - { - foreach (var error in errors) - { - Console.WriteLine(error.Message); - } - } -} -``` - # Next Steps - [MCP Adapter](/docs/hotchocolate/v16/guides/mcp-adapter) to expose your GraphQL schema as MCP tools for AI agents. diff --git a/website/src/docs/hotchocolate/v16/guides/performance.md b/website/src/docs/hotchocolate/v16/guides/performance.md index 4fc61a298d8..418b688d003 100644 --- a/website/src/docs/hotchocolate/v16/guides/performance.md +++ b/website/src/docs/hotchocolate/v16/guides/performance.md @@ -226,20 +226,6 @@ Diagnostic event handlers execute synchronously as part of the GraphQL request. [Learn more about instrumentation](/docs/hotchocolate/v16/server/instrumentation) -# Troubleshooting - -## Cache hit rate is low despite stable operations - -The operation name is part of the cache key. If clients send the same document with different operation names, each variant occupies a separate cache slot. Verify that your clients use consistent operation names. If the number of distinct operations exceeds your cache size, increase `PreparedOperationCacheSize`. - -## Projections do not reduce the SQL query - -Verify that the resolver returns `IQueryable` and that `[UseProjection]` is applied. If you are using `QueryContext`, do not also apply `[UseProjection]` on the same field. Check that projected properties have public setters. - -## DataLoader dispatches too many batches - -By default, the batch dispatcher waits up to 50ms before dispatching. If you see many small batches, verify that your resolvers are structured so that sibling fields resolve in the same execution step. Deeply nested resolver chains can cause sequential dispatches rather than batched ones. - # Next Steps - **Server warmup:** [Warmup](/docs/hotchocolate/v16/server/warmup) covers custom warmup tasks and lazy initialization. diff --git a/website/src/docs/hotchocolate/v16/guides/private-api.md b/website/src/docs/hotchocolate/v16/guides/private-api.md index e3aa2ff82ec..04db51aea19 100644 --- a/website/src/docs/hotchocolate/v16/guides/private-api.md +++ b/website/src/docs/hotchocolate/v16/guides/private-api.md @@ -330,59 +330,6 @@ app.Run(); The private API setup is shorter, has fewer knobs to tune, and provides a stronger security guarantee. The tradeoff is the build-time extraction step, which your client tooling handles automatically. -# Troubleshooting - -## "PersistedQueryNotFound" error - -The server cannot find an operation matching the hash sent by the client. Verify that: - -- The operation files are present in the configured storage directory. -- The file names match the format `{hash}.graphql`. -- The server process has read access to the directory. - -If you are using the Nitro client registry, confirm that the client version has been published and that the API ID and stage match your server configuration. - -## Hash mismatch between client and server - -The client and server must use the same hashing algorithm and encoding format. Hot Chocolate defaults to MD5 with hex encoding. If your client uses SHA256 or a different encoding, configure the server to match: - -```csharp -// Program.cs -builder.Services - .AddGraphQLServer() - .AddSha256DocumentHashProvider(HashFormat.Hex) - .UsePersistedOperationPipeline() - .AddFileSystemOperationDocumentStorage("./persisted-operations"); -``` - -Check your client's build output to see which algorithm and format it uses. - -## Operations blocked during development - -If `OnlyAllowPersistedDocuments` is enabled and you are sending ad-hoc queries during development, the server rejects them. Either switch to `UseAutomaticPersistedOperationPipeline()` for your development environment or add an HTTP request interceptor that calls `AllowNonPersistedOperation()` for developer requests. See [Development workflow](#development-workflow) above. - -## Relay sends "doc_id" instead of "id" - -Relay's default network layer uses `doc_id` as the field name for the operation hash. Hot Chocolate expects `id`. Update your Relay network layer to send `id`: - -```js -// relay-network.js -function fetchQuery(operation, variables) { - return fetch("/graphql", { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({ - id: operation.id, // not doc_id - variables, - }), - }).then((response) => response.json()); -} -``` - -## Stale operations after schema changes - -When you change your GraphQL schema, previously extracted operations may no longer be valid. Re-run the client build to extract updated operations and redeploy them to the server. The [Nitro client registry](/docs/nitro/apis/client-registry) catches these mismatches automatically during the validation step. - # Next Steps - **Need to set up persisted operations storage?** See [Persisted Operations](/docs/hotchocolate/v16/performance/trusted-documents) for filesystem, Redis, and Azure Blob Storage options. diff --git a/website/src/docs/hotchocolate/v16/guides/public-api.md b/website/src/docs/hotchocolate/v16/guides/public-api.md index f1387401274..79333170179 100644 --- a/website/src/docs/hotchocolate/v16/guides/public-api.md +++ b/website/src/docs/hotchocolate/v16/guides/public-api.md @@ -372,28 +372,6 @@ app.Run(); Adjust the specific values (`MaxPageSize`, `MaxFieldCost`, `MaxTypeCost`, depth limit, rate limit window) to match your schema and infrastructure. Use the `GraphQL-Cost: report` header to measure real query costs and tune from there. -# Troubleshooting - -## Legitimate client queries are rejected by cost analysis - -Send the query with the `GraphQL-Cost: report` header to inspect its field cost and type cost. Common causes: the query fans out across multiple paginated fields, or a resolver has a high default cost. Either increase `MaxFieldCost`/`MaxTypeCost` or reduce `MaxPageSize` on the specific fields that cause the fan-out. - -## Clients receive "first or last argument required" errors - -This happens when `RequirePagingBoundaries` is enabled and the client does not specify `first` or `last` on a paginated field. This is the intended behavior for public APIs. Document the requirement in your API guide and include `first` in your example queries. - -## Authorization errors for authenticated users - -Verify you are using `HotChocolate.Authorization.AuthorizeAttribute`, not `Microsoft.AspNetCore.Authorization.AuthorizeAttribute`. Also check that `AddAuthorization()` is called on both `IServiceCollection` and `IRequestExecutorBuilder`, and that `UseAuthentication()` comes before `UseAuthorization()` in the middleware pipeline. - -## Introspection works in development but not in production - -If you used `AllowIntrospection(builder.Environment.IsDevelopment())`, introspection is disabled in all non-development environments. This is typically what you want. If you need introspection in production for specific clients, use a request interceptor to allow it based on authentication. - -## Rate limiting does not seem to apply - -Ensure `app.UseRateLimiter()` is called before `app.UseEndpoints()` in the middleware pipeline, and that `RequireRateLimiting("graphql")` is chained onto `MapGraphQL()`. Also verify that the rate limiter policy name matches between `AddFixedWindowLimiter` and `RequireRateLimiting`. - # Next Steps - **Cost analysis reference:** [Cost Analysis](/docs/hotchocolate/v16/securing-your-api/cost-analysis) covers all options, custom weights, filtering and sorting costs, and the tuning guide. diff --git a/website/src/docs/hotchocolate/v16/guides/schema-evolution.md b/website/src/docs/hotchocolate/v16/guides/schema-evolution.md index 6af88773bea..f659d8751b6 100644 --- a/website/src/docs/hotchocolate/v16/guides/schema-evolution.md +++ b/website/src/docs/hotchocolate/v16/guides/schema-evolution.md @@ -298,20 +298,6 @@ When you need to make a breaking change, follow this sequence: 3. Wait for consumers to migrate (monitor usage if possible). 4. Remove the deprecated field. -# Troubleshooting - -## Deprecated field still returned in queries - -Deprecation does not remove a field. The field continues to work normally. Deprecation marks the field in introspection so tools can warn consumers. Remove the field from the schema when you are confident no consumers depend on it. - -## Opt-in field not visible in introspection - -Fields with `@requiresOptIn` are hidden by default. Use the `includeOptIn` argument in introspection queries to reveal them. Also verify that `EnableOptInFeatures = true` is set in your schema options. - -## Descriptions not appearing in schema - -Verify that `GenerateDocumentationFile` is set to `true` in your `.csproj`. Without this setting, the XML file is not generated and Hot Chocolate has no documentation to read. - # Next Steps - **Schema documentation reference:** [Documentation](/docs/hotchocolate/v16/building-a-schema/documentation) covers `[GraphQLDescription]`, XML docs, and priority order. diff --git a/website/src/docs/hotchocolate/v16/guides/testing.md b/website/src/docs/hotchocolate/v16/guides/testing.md index eeedd2d0f46..187fd7daba2 100644 --- a/website/src/docs/hotchocolate/v16/guides/testing.md +++ b/website/src/docs/hotchocolate/v16/guides/testing.md @@ -309,20 +309,6 @@ public async Task Error_Filter_Masks_Internal_Errors() } ``` -# Troubleshooting - -## Test hangs on BuildRequestExecutorAsync - -This can happen when a required service is missing from the `ServiceCollection`. Check that all services your resolvers inject are registered. The executor build step resolves all types and their dependencies at startup. - -## Snapshot mismatch after intentional change - -Delete the old snapshot file from the `__snapshots__/` directory and re-run the test. CookieCrumble creates a new snapshot with the updated output. Review the new snapshot to confirm it matches your expectation. - -## ExpectOperationResult throws an exception - -`ExpectOperationResult()` throws if the execution result is not a standard operation result (for example, if it is a streaming result from `@defer` or `@stream`). For streaming results, use the appropriate streaming result type instead. - # Next Steps - **Error handling reference:** [Error Handling Guide](/docs/hotchocolate/v16/guides/error-handling) covers error types, error filters, and how to structure error responses. diff --git a/website/src/docs/hotchocolate/v16/integrations/entity-framework.md b/website/src/docs/hotchocolate/v16/integrations/entity-framework.md index 23370f5ceb7..fbcf5f139d7 100644 --- a/website/src/docs/hotchocolate/v16/integrations/entity-framework.md +++ b/website/src/docs/hotchocolate/v16/integrations/entity-framework.md @@ -225,17 +225,6 @@ Take a look at the annotation-based or code-first example. > Warning: Dispose the `DbContext` when the service is disposed. The example above implements `IAsyncDisposable` and disposes the `DbContext` in `DisposeAsync`. -# Troubleshooting - -**"A second operation started on this context before a previous operation completed"** -This error means multiple resolvers share the same `DbContext` instance in parallel. Use the default resolver scope (which creates a separate `DbContext` per resolver for queries) or switch to a `DbContext` factory. - -**DbContext is not injected into the resolver** -Verify that you registered the factory with `RegisterDbContextFactory()` on the `IRequestExecutorBuilder` and that the `DbContextFactory` is also registered in the DI container. - -**DbContext is disposed before use in DataLoaders** -Create the `DbContext` inside the `LoadBatchAsync` method and dispose it there. Do not create it in the constructor. - # Next Steps - [Dependency Injection](/docs/hotchocolate/v16/resolvers-and-data/dependency-injection) for DI scope configuration diff --git a/website/src/docs/hotchocolate/v16/integrations/marten.md b/website/src/docs/hotchocolate/v16/integrations/marten.md index e0b3ba13204..d296c1a7411 100644 --- a/website/src/docs/hotchocolate/v16/integrations/marten.md +++ b/website/src/docs/hotchocolate/v16/integrations/marten.md @@ -51,14 +51,6 @@ Pagination works out of the box with Marten. No custom configuration is needed. [Learn more about pagination](/docs/hotchocolate/v16/resolvers-and-data/pagination). -# Troubleshooting - -**Filtering produces unexpected results or errors** -Verify that you registered `AddMartenFiltering()` instead of the default `AddFiltering()`. The Marten convention translates LINQ expressions into a format compatible with the Marten LINQ provider. - -**Sorting does not apply correctly** -Confirm that you registered `AddMartenSorting()`. The default sorting convention may generate expressions that the Marten LINQ provider cannot process. - # Next Steps - [Filtering](/docs/hotchocolate/v16/resolvers-and-data/filtering) for filtering concepts diff --git a/website/src/docs/hotchocolate/v16/integrations/mongodb.md b/website/src/docs/hotchocolate/v16/integrations/mongodb.md index b96298dc348..1789de3ed98 100644 --- a/website/src/docs/hotchocolate/v16/integrations/mongodb.md +++ b/website/src/docs/hotchocolate/v16/integrations/mongodb.md @@ -216,17 +216,6 @@ public IExecutable GetPersonById( } ``` -# Troubleshooting - -**Filters are not applied to the query** -Verify that you registered `AddMongoDbFiltering()` on the schema builder. If you are using MongoDB alongside `IQueryable`, confirm that you set the correct scope on both the registration and the resolver attribute. - -**Sorting has no effect** -Confirm that `AddMongoDbSorting()` is registered. Check that the field names in the sort input match the property names in your MongoDB model. - -**Projections cause errors or unexpected results** -Not all query patterns benefit from projections. If you encounter issues, try removing `[UseProjection]` to determine whether projections are the cause. - # Next Steps - [Pagination](/docs/hotchocolate/v16/resolvers-and-data/pagination) for pagination setup diff --git a/website/src/docs/hotchocolate/v16/integrations/spatial-data.md b/website/src/docs/hotchocolate/v16/integrations/spatial-data.md index 57ded34f218..d34ab05582a 100644 --- a/website/src/docs/hotchocolate/v16/integrations/spatial-data.md +++ b/website/src/docs/hotchocolate/v16/integrations/spatial-data.md @@ -317,17 +317,6 @@ The `within` filter is an implementation of `Geometry.Within`. The negation is `nwithin`. -# Troubleshooting - -**Spatial types not appearing in the schema** -Verify that `AddSpatialTypes()` is called on the schema builder. If you are using filtering or projections, also call `AddSpatialFiltering()` or `AddSpatialProjections()`. - -**"No handler found" error for spatial filter operations** -Ensure that both `AddFiltering()` and `AddSpatialFiltering()` are registered. - -**Coordinate reference system mismatch** -The CRS is currently fixed. The user must know the CRS of the backend to perform spatial filtering. Re-projection features are planned for future releases. - # Next Steps - [Filtering](/docs/hotchocolate/v16/resolvers-and-data/filtering) for general filtering concepts diff --git a/website/src/docs/hotchocolate/v16/performance/automatic-persisted-operations.md b/website/src/docs/hotchocolate/v16/performance/automatic-persisted-operations.md index 554e6618564..a561446e922 100644 --- a/website/src/docs/hotchocolate/v16/performance/automatic-persisted-operations.md +++ b/website/src/docs/hotchocolate/v16/performance/automatic-persisted-operations.md @@ -281,20 +281,6 @@ curl -g 'http://localhost:5000/graphql/?extensions={"persistedQuery":{"version": { "data": { "__typename": "Query" } } ``` -# Troubleshooting - -## "PersistedQueryNotFound" on every request - -The in-memory storage is lost on server restart. If you need persistence across restarts, use a Redis or filesystem-based operation document storage. - -## Hash mismatch between client and server - -Verify that both the client and server use the same hashing algorithm (MD5, SHA1, or SHA256) and the same encoding format (Base64 or Hex). - -## Operations not persisted in Redis - -Check that the Redis connection string is correct and the server can connect to the Redis instance. Verify the Redis instance is running and accessible from the server. - # Next Steps - [Persisted Operations](/docs/hotchocolate/v16/performance/trusted-documents) for pre-registering operations ahead of deployment. diff --git a/website/src/docs/hotchocolate/v16/performance/trusted-documents.md b/website/src/docs/hotchocolate/v16/performance/trusted-documents.md index 103e91845e3..a0bf7204a13 100644 --- a/website/src/docs/hotchocolate/v16/performance/trusted-documents.md +++ b/website/src/docs/hotchocolate/v16/performance/trusted-documents.md @@ -239,20 +239,6 @@ A client is expected to send an `id` field containing the operation document has > Note: [Relay's persisted queries documentation](https://relay.dev/docs/guides/persisted-queries/#network-layer-changes) uses `doc_id` instead of `id`. Be sure to change it to `id`. -# Troubleshooting - -## "PersistedQueryNotFound" error - -Verify that the operation document is stored in the configured storage (filesystem, Redis, or Azure Blob Storage) with the correct hash as the key. Check that the hashing algorithm and format (Base64 vs Hex) match between client and server. - -## Dynamic operations blocked unexpectedly - -If `OnlyAllowPersistedDocuments` is enabled, all requests without a valid `id` are rejected. Use a custom HTTP request interceptor to allow specific requests through. - -## Hash mismatch between client and server - -Ensure both the client and server use the same hashing algorithm (MD5, SHA1, or SHA256) and the same encoding format (Base64 or Hex). - # Next Steps - [Automatic Persisted Operations](/docs/hotchocolate/v16/performance/automatic-persisted-operations) for dynamically storing operations at runtime. diff --git a/website/src/docs/hotchocolate/v16/resolvers-and-data/dataloader.md b/website/src/docs/hotchocolate/v16/resolvers-and-data/dataloader.md index f3b3295170c..4b7c37958e9 100644 --- a/website/src/docs/hotchocolate/v16/resolvers-and-data/dataloader.md +++ b/website/src/docs/hotchocolate/v16/resolvers-and-data/dataloader.md @@ -359,26 +359,6 @@ public class BrandByIdDataLoader : BatchDataLoader > The `IReadOnlyList` passed to `LoadBatchAsync` and source-generated methods is a rented list. Do not store or use it outside the method body. -# Troubleshooting - -## DataLoader returns null for a key that exists - -The dictionary returned from your DataLoader method must use the same key values that were passed in. If you use a database column that does not match the requested key (for example, returning a dictionary keyed by `string` when the DataLoader expects `int`), the DataLoader cannot match results to requests and returns null. - -Verify that your `ToDictionaryAsync` key selector matches the key type of your DataLoader. - -## N+1 queries still appearing - -If you see individual queries instead of batched ones, check that you are injecting the DataLoader interface (like `IBrandByIdDataLoader`) into your resolver, not calling the database directly. Also verify that the DataLoader method is marked with `[DataLoader]` and the source generator is running (check for the generated `AddTypes` method in your build output). - -## Batch resolver returns wrong number of results - -A batch resolver must return a list with the same count as the input parent list. If the counts do not match, the execution engine raises an error. Verify that your method produces one result per input parent, in the same order. - -## Scoped service disposed before DataLoader executes - -If your `DbContext` or other scoped service is disposed before the DataLoader batch runs, use `DataLoaderServiceScope.DataLoaderScope` on the `[DataLoader]` attribute. This creates a dedicated service scope for the DataLoader, preventing the service from being disposed when the request scope ends. - # Next Steps - **Need to understand resolver basics?** See [Resolvers](/docs/hotchocolate/v16/resolvers-and-data/resolvers). diff --git a/website/src/docs/hotchocolate/v16/resolvers-and-data/dependency-injection.md b/website/src/docs/hotchocolate/v16/resolvers-and-data/dependency-injection.md index 5e022ad7a1e..e3bd74cf113 100644 --- a/website/src/docs/hotchocolate/v16/resolvers-and-data/dependency-injection.md +++ b/website/src/docs/hotchocolate/v16/resolvers-and-data/dependency-injection.md @@ -299,20 +299,6 @@ builder.Services [Learn more about interceptors](/docs/hotchocolate/v16/server/interceptors) -# Troubleshooting - -## Service not injected into resolver - -Verify that the service is registered in the DI container. In v16, the `[Service]` attribute is no longer required for standard (non-keyed) services. If the parameter type matches a registered service, it is injected automatically. If you are using a keyed service, you must apply `[Service("key")]`. - -## Service behaves as a singleton unexpectedly - -Check that you are not injecting the service through a constructor on a GraphQL type class. GraphQL types are singletons, which means any constructor-injected dependency also becomes a singleton. Use resolver method parameters instead. - -## Application service not available in diagnostic listener - -If you inject an application service into a schema-level component (such as a diagnostic event listener), you must cross-register the service using `AddApplicationService()` on the `IRequestExecutorBuilder`. - # Next Steps - [Interceptors](/docs/hotchocolate/v16/server/interceptors) for setting request-scoped state and services. diff --git a/website/src/docs/hotchocolate/v16/resolvers-and-data/fetching-from-databases.md b/website/src/docs/hotchocolate/v16/resolvers-and-data/fetching-from-databases.md index ad4344aac62..674ced25a5f 100644 --- a/website/src/docs/hotchocolate/v16/resolvers-and-data/fetching-from-databases.md +++ b/website/src/docs/hotchocolate/v16/resolvers-and-data/fetching-from-databases.md @@ -113,16 +113,6 @@ When you return `IQueryable`, the pagination, projection, filtering, and sort [Learn more about the Entity Framework integration](/docs/hotchocolate/v16/integrations/entity-framework) -# Troubleshooting - -## DbContext concurrency issues - -If you see errors about concurrent operations on a `DbContext`, register it with `AddDbContextPool` or `AddPooledDbContextFactory`. Hot Chocolate runs sibling resolvers in parallel, so each resolver needs its own `DbContext` instance. - -## Resolver returns stale data - -EF Core tracks entities in the change tracker. If you modify an entity in one resolver and read it in another within the same request, the change tracker may return the cached version. Use `.AsNoTracking()` for read-only queries to avoid this. - # Next Steps - **Need to batch database calls?** See [DataLoader](/docs/hotchocolate/v16/resolvers-and-data/dataloader). diff --git a/website/src/docs/hotchocolate/v16/resolvers-and-data/fetching-from-rest.md b/website/src/docs/hotchocolate/v16/resolvers-and-data/fetching-from-rest.md index ebec174be58..6f99f87a351 100644 --- a/website/src/docs/hotchocolate/v16/resolvers-and-data/fetching-from-rest.md +++ b/website/src/docs/hotchocolate/v16/resolvers-and-data/fetching-from-rest.md @@ -157,20 +157,6 @@ public class TodoByIdDataLoader : BatchDataLoader } ``` -# Troubleshooting - -## Generated client throws serialization errors - -Verify that the `Newtonsoft.Json` package is installed and the generated client version matches the OpenAPI spec version. Regenerate the client if the REST API schema has changed. - -## HTTP calls are slow or timing out - -Register the generated client with `AddHttpClient()` to leverage `HttpClientFactory`, which manages connection pooling and lifetime. Set appropriate timeouts on the `HttpClient`. - -## N+1 requests to the REST API - -If you see one HTTP request per item in a list, add a DataLoader to batch the calls. Without batching, each GraphQL field triggers a separate REST call. - # Next Steps - **Need to batch REST calls?** See [DataLoader](/docs/hotchocolate/v16/resolvers-and-data/dataloader). diff --git a/website/src/docs/hotchocolate/v16/resolvers-and-data/filtering.md b/website/src/docs/hotchocolate/v16/resolvers-and-data/filtering.md index 03f8c2854fe..ab5c0132ba1 100644 --- a/website/src/docs/hotchocolate/v16/resolvers-and-data/filtering.md +++ b/website/src/docs/hotchocolate/v16/resolvers-and-data/filtering.md @@ -306,24 +306,6 @@ builder.Services .BindRuntimeType()); ``` -# Troubleshooting - -## Filter argument not appearing on the field - -Verify that `AddFiltering()` is called on the schema builder and `[UseFiltering]` is applied to the resolver. Both are required. - -## "or" filter behaves like "and" - -The `or` combinator must be used at the top level of the `where` argument. Placing `or` inside a field's operation object results in `and` behavior. Use the array syntax: `where: { or: [{ ... }, { ... }] }`. - -## Custom scalar not recognized by filter - -Register the filter type for your custom scalar through the filter convention using `BindRuntimeType`. Built-in scalars are bound automatically, but custom scalars require explicit binding. - -## Filters not translating to SQL - -Ensure your resolver returns `IQueryable`, not `IEnumerable`. When you return `IEnumerable`, filters are applied in memory after loading all data from the database. - # Next Steps - **Need to sort results?** See [Sorting](/docs/hotchocolate/v16/resolvers-and-data/sorting). diff --git a/website/src/docs/hotchocolate/v16/resolvers-and-data/index.md b/website/src/docs/hotchocolate/v16/resolvers-and-data/index.md index 45273134922..1d962f2c43f 100644 --- a/website/src/docs/hotchocolate/v16/resolvers-and-data/index.md +++ b/website/src/docs/hotchocolate/v16/resolvers-and-data/index.md @@ -78,16 +78,6 @@ Hot Chocolate is not bound to a specific database or architecture. You can fetch - [Fetching from databases](/docs/hotchocolate/v16/resolvers-and-data/fetching-from-databases) - [Fetching from REST APIs](/docs/hotchocolate/v16/resolvers-and-data/fetching-from-rest) -# Troubleshooting - -## Resolver returns null unexpectedly - -Verify that your resolver returns the correct type. If it returns `Task`, ensure you `await` the result. Check that any injected services are registered in the DI container. - -## N+1 query problem - -If you see one database query per item in a list, you are likely missing a DataLoader. Use a [DataLoader](/docs/hotchocolate/v16/resolvers-and-data/dataloader) to batch and deduplicate requests. - # Next Steps - **New to resolvers?** Start with [Resolvers](/docs/hotchocolate/v16/resolvers-and-data/resolvers). diff --git a/website/src/docs/hotchocolate/v16/resolvers-and-data/pagination.md b/website/src/docs/hotchocolate/v16/resolvers-and-data/pagination.md index a6bed41201b..af0c4c327b1 100644 --- a/website/src/docs/hotchocolate/v16/resolvers-and-data/pagination.md +++ b/website/src/docs/hotchocolate/v16/resolvers-and-data/pagination.md @@ -375,24 +375,6 @@ If no `ProviderName` is specified, the correct provider is selected based on the [Learn more about database integrations](/docs/hotchocolate/v16/integrations) -# Troubleshooting - -## "Cannot determine the element type" error - -Ensure your resolver returns `IEnumerable`, `IQueryable`, or `Connection`. If the return type is untyped (like `IEnumerable` without a generic argument), the paging middleware cannot determine the node type. - -## Missing `totalCount` field - -Enable `IncludeTotalCount` in `PagingOptions` or on the `[UsePaging]` attribute. This field is opt-in because computing the total count requires an additional database query. - -## Cursors appear to be wrong after sorting changes - -Cursors encode the position of an item based on the sort order at the time of the query. If you change the sort order between pages, cursors from the previous page may point to the wrong position. Ensure the sort order remains consistent across paginated requests. - -## "Nullable cursor key requires NullOrdering" error - -You have a nullable field as a cursor key and the paging handler cannot detect your database's null ordering behavior. Set `NullOrdering` explicitly in `PagingOptions`. - # Next Steps - **Need to filter results?** See [Filtering](/docs/hotchocolate/v16/resolvers-and-data/filtering). diff --git a/website/src/docs/hotchocolate/v16/resolvers-and-data/projections.md b/website/src/docs/hotchocolate/v16/resolvers-and-data/projections.md index 08991fb910d..709f16d15bc 100644 --- a/website/src/docs/hotchocolate/v16/resolvers-and-data/projections.md +++ b/website/src/docs/hotchocolate/v16/resolvers-and-data/projections.md @@ -271,24 +271,6 @@ public class UserType : ObjectType -# Troubleshooting - -## Properties return default values - -Projections require a public setter on each property they operate on. If a property has only a getter (or uses `init`), the projected value cannot be assigned and the default value is returned. - -## HC0099: Do not combine QueryContext with UseProjection - -Remove either `[UseProjection]` or `QueryContext`. Using both on the same field produces conflicting projection behavior. - -## Nested properties are null - -Verify that the navigation property is included in the EF Core model. If the relationship is not configured in the database context, the projection middleware cannot include it in the query. - -## All columns are loaded despite using projections - -Ensure the resolver returns `IQueryable`, not a materialized collection. If you call `.ToList()` or `.AsEnumerable()` before returning, the projection middleware has no `IQueryable` to apply `Select` to. - # Next Steps - **Need to filter results?** See [Filtering](/docs/hotchocolate/v16/resolvers-and-data/filtering). diff --git a/website/src/docs/hotchocolate/v16/resolvers-and-data/resolvers.md b/website/src/docs/hotchocolate/v16/resolvers-and-data/resolvers.md index c37ff8dcdc9..75ae32c38a2 100644 --- a/website/src/docs/hotchocolate/v16/resolvers-and-data/resolvers.md +++ b/website/src/docs/hotchocolate/v16/resolvers-and-data/resolvers.md @@ -329,24 +329,6 @@ public static partial class UserQueries When the client query includes the `address` field, `includeAddress` is `true` and the resolver loads the address eagerly. Otherwise, it skips the additional work. -# Troubleshooting - -## Resolver not appearing in the schema - -Verify the method is `public`. Private, internal, and protected methods are not exposed as fields. Check that the class has the correct attribute (`[QueryType]`, `[MutationType]`, or `[ExtendObjectType]`) and is marked `partial` when using the source generator. - -## Service not injected - -Confirm the service is registered in the DI container. In v16, services are auto-recognized without `[Service]`, but the type must match exactly. If you register `IMyService` but the parameter is `MyService`, Hot Chocolate cannot resolve it. - -## CancellationToken not canceling - -Ensure you pass the `CancellationToken` through to your async calls. If you use `CancellationToken.None` or ignore the token, Hot Chocolate cannot cancel the operation when the client disconnects. - -## Parent value is null - -When using `[Parent]`, verify that the parent resolver actually returns a non-null value. If the parent field is nullable and resolves to `null`, child resolvers do not execute. - # Next Steps - **Need to batch data access?** See [DataLoader](/docs/hotchocolate/v16/resolvers-and-data/dataloader). diff --git a/website/src/docs/hotchocolate/v16/resolvers-and-data/sorting.md b/website/src/docs/hotchocolate/v16/resolvers-and-data/sorting.md index 7fa31a7d661..e549596bc3c 100644 --- a/website/src/docs/hotchocolate/v16/resolvers-and-data/sorting.md +++ b/website/src/docs/hotchocolate/v16/resolvers-and-data/sorting.md @@ -259,24 +259,6 @@ For fields where no explicit binding exists, `DefaultSortEnumType` (with `ASC` a descriptor.AddDefaults().DefaultBinding(); ``` -# Troubleshooting - -## Sort argument not appearing on the field - -Verify that `AddSorting()` is called on the schema builder and `[UseSorting]` is applied to the resolver. Both are required. - -## Sorting not translating to SQL - -Ensure your resolver returns `IQueryable`, not `IEnumerable`. When you return `IEnumerable`, sorting happens in memory after loading all data from the database. - -## Collection properties appear in sort input - -Sorting does not apply to collection properties because ordering by a list is not meaningful. If collection properties appear in your sort type, you may need to use `BindFieldsExplicitly` and specify only the fields you want. - -## Null values sort in unexpected order - -Set `NullOrdering` in `PagingOptions` to match your database's native behavior. PostgreSQL defaults to nulls-last, while SQL Server defaults to nulls-first. - # Next Steps - **Need to filter results?** See [Filtering](/docs/hotchocolate/v16/resolvers-and-data/filtering). diff --git a/website/src/docs/hotchocolate/v16/securing-your-api/authentication.md b/website/src/docs/hotchocolate/v16/securing-your-api/authentication.md index e9438a0214c..e1ec9f01e31 100644 --- a/website/src/docs/hotchocolate/v16/securing-your-api/authentication.md +++ b/website/src/docs/hotchocolate/v16/securing-your-api/authentication.md @@ -167,24 +167,6 @@ builder.Services [Learn more about interceptors](/docs/hotchocolate/v16/server/interceptors) -# Troubleshooting - -## ClaimsPrincipal is empty or unauthenticated - -Verify that `UseAuthentication()` is called before `MapGraphQL()` in the middleware pipeline. If the middleware order is incorrect, the authentication handler never processes the request. - -## JWT token is not validated - -Check that the token validation parameters (issuer, audience, signing key) match the values used to generate the token. Enable detailed errors in development to see the specific validation failure. - -## "Bearer error=invalid_token" in response headers - -This usually means the token is expired or the signing key does not match. Inspect the token at [jwt.io](https://jwt.io) to verify its claims and expiration. - -## Claims are missing - -Verify that the identity provider includes the expected claims in the token. Some providers require explicit scope or claim configuration. Check the `ClaimsPrincipal.Claims` collection in a resolver to see what was parsed. - # Next Steps - **Need to restrict access to fields?** See [Authorization](/docs/hotchocolate/v16/securing-your-api/authorization). diff --git a/website/src/docs/hotchocolate/v16/securing-your-api/authorization.md b/website/src/docs/hotchocolate/v16/securing-your-api/authorization.md index 5344588f3c8..3bc5c54c758 100644 --- a/website/src/docs/hotchocolate/v16/securing-your-api/authorization.md +++ b/website/src/docs/hotchocolate/v16/securing-your-api/authorization.md @@ -334,24 +334,6 @@ app.UseEndpoints(endpoints => [Learn more about available middleware](/docs/hotchocolate/v16/server/endpoints) -# Troubleshooting - -## Authorization not enforced - -Verify you are using `HotChocolate.Authorization.AuthorizeAttribute`, not `Microsoft.AspNetCore.Authorization.AuthorizeAttribute`. The Microsoft attribute is ignored by the Hot Chocolate pipeline. - -## "AUTH_NOT_AUTHENTICATED" for authenticated users - -Check the middleware order: `UseAuthentication()` must come before `UseAuthorization()`, and both must come before `MapGraphQL()`. Also verify that `AddAuthorization()` is called on both `IServiceCollection` and `IRequestExecutorBuilder`. - -## Policy always fails - -Verify that the `AuthorizationHandler` is registered in the DI container and that the handler calls `context.Succeed(requirement)` when the requirement is met. A handler that does not call `Succeed` results in an implicit failure. - -## Nitro is blocked by global authorization - -When `RequireAuthorization()` is applied to `MapGraphQL()`, it blocks all sub-middleware including Nitro. Split the middleware into `MapGraphQLHttp()` and `MapNitroApp()` and apply authorization only to `MapGraphQLHttp()`. - # Next Steps - **Need to set up authentication first?** See [Authentication](/docs/hotchocolate/v16/securing-your-api/authentication). diff --git a/website/src/docs/hotchocolate/v16/securing-your-api/cost-analysis.md b/website/src/docs/hotchocolate/v16/securing-your-api/cost-analysis.md index 7db84b2ea1d..6dabdb39cb5 100644 --- a/website/src/docs/hotchocolate/v16/securing-your-api/cost-analysis.md +++ b/website/src/docs/hotchocolate/v16/securing-your-api/cost-analysis.md @@ -394,24 +394,6 @@ builder.Services .ModifyCostOptions(o => o.EnforceCostLimits = false); ``` -# Troubleshooting - -## Legitimate queries are rejected - -Use the `GraphQL-Cost: report` header to inspect the cost of the rejected query. Common causes: the query fans out across multiple paginated fields, or a field has an unexpectedly high default cost. Increase `MaxFieldCost`/`MaxTypeCost` or reduce `MaxPageSize` on specific fields. - -## Cost seems too high for a small query - -Check whether the query includes paginated fields without specifying `first` or `last`. Without a slicing argument, cost analysis uses `MaxPageSize` (default 50) as the assumed list size. Enable `RequirePagingBoundaries` to force clients to specify the page size. - -## Cost metrics differ between environments - -Cost calculation depends on the schema and cost configuration. If different environments have different `MaxPageSize` or cost weights, the metrics will differ. Keep cost configuration consistent across environments. - -## Variable-based filters have unexpectedly high cost - -When a filter argument is provided as a variable (rather than inline), the analyzer cannot inspect its structure at validation time. It applies a `VariableMultiplier` (default 5) to account for worst-case complexity. This is intentional. Adjust `VariableMultiplier` if the default is too conservative. - # Next Steps - **Need to restrict access to fields?** See [Authorization](/docs/hotchocolate/v16/securing-your-api/authorization). diff --git a/website/src/docs/hotchocolate/v16/securing-your-api/index.md b/website/src/docs/hotchocolate/v16/securing-your-api/index.md index c518ff36dde..91533f88f38 100644 --- a/website/src/docs/hotchocolate/v16/securing-your-api/index.md +++ b/website/src/docs/hotchocolate/v16/securing-your-api/index.md @@ -112,29 +112,6 @@ builder.Services [Learn more about hashing providers](/docs/hotchocolate/v16/performance/trusted-documents#hashing-algorithms) -# Troubleshooting - -## Queries rejected with cost exceeded error - -Review your cost analysis configuration. The default limits (`MaxFieldCost = 1000`, `MaxTypeCost = 1000`) may be too low for your schema. Use the `GraphQL-Cost: report` header to inspect the cost of your queries before adjusting limits. - -[Learn how to tune cost analysis](/docs/hotchocolate/v16/securing-your-api/cost-analysis) - -## Authenticated users receive "not authorized" errors - -Verify the middleware order in your pipeline: `UseAuthentication()` must come before `UseAuthorization()`. Also check that `AddAuthorization()` is called on both `IServiceCollection` and `IRequestExecutorBuilder`. - -## Introspection disabled in development - -If introspection is disabled and you cannot use Nitro, enable it conditionally: - -```csharp -if (app.Environment.IsDevelopment()) -{ - // Introspection is allowed by default -} -``` - # Next Steps - **Building a public API?** Start with [Cost Analysis](/docs/hotchocolate/v16/securing-your-api/cost-analysis). diff --git a/website/src/docs/hotchocolate/v16/securing-your-api/introspection.md b/website/src/docs/hotchocolate/v16/securing-your-api/introspection.md index dd49d0eaf56..139c2030794 100644 --- a/website/src/docs/hotchocolate/v16/securing-your-api/introspection.md +++ b/website/src/docs/hotchocolate/v16/securing-your-api/introspection.md @@ -161,16 +161,6 @@ public class IntrospectionInterceptor : DefaultHttpRequestInterceptor } ``` -# Troubleshooting - -## Introspection queries fail in development - -Verify that `AllowIntrospection` is set to `true` (or uses `builder.Environment.IsDevelopment()`) in your GraphQL server configuration. When using a per-request interceptor, check that the expected header is being sent. - -## Nitro cannot load the schema - -If Nitro cannot load the schema, introspection might be disabled. Enable it for development environments or configure the interceptor to allow introspection for Nitro requests. - # Next Steps - [Interceptors](/docs/hotchocolate/v16/server/interceptors) for per-request customization. diff --git a/website/src/docs/hotchocolate/v16/server/batching.md b/website/src/docs/hotchocolate/v16/server/batching.md index 8d18e01908f..0b230c5c8d2 100644 --- a/website/src/docs/hotchocolate/v16/server/batching.md +++ b/website/src/docs/hotchocolate/v16/server/batching.md @@ -163,20 +163,6 @@ If you are using a JavaScript client, consider: For more details about streaming transports, see [HTTP Transport](/docs/hotchocolate/v16/server/http-transport#streaming-transports). -# Troubleshooting - -## "Batching is not allowed" error - -Batching is disabled by default in v16. Enable it by calling `ModifyServerOptions` and setting the `Batching` property to the appropriate `AllowedBatching` flag. - -## Batch exceeds maximum size - -The default maximum batch size is 1024 operations. If you need a larger batch, increase the limit with `ModifyServerOptions(o => o.MaxBatchSize = )`. Setting it to `0` removes the limit. - -## Results arriving out of order - -This is expected behavior. Batch results stream back as they complete. Use the `requestIndex` and `variableIndex` fields in the response to correlate results with their corresponding requests. - # Next Steps - [HTTP Transport](/docs/hotchocolate/v16/server/http-transport) for details on streaming transports and incremental delivery. diff --git a/website/src/docs/hotchocolate/v16/server/command-line.md b/website/src/docs/hotchocolate/v16/server/command-line.md index e3d9203df30..e547876baab 100644 --- a/website/src/docs/hotchocolate/v16/server/command-line.md +++ b/website/src/docs/hotchocolate/v16/server/command-line.md @@ -37,16 +37,6 @@ dotnet run -- schema export --output schema.graphql - `--output`: The path to the file where the schema is exported. If no output path is specified, the schema prints to the console. - `--schema-name`: The name of the schema to export. If no schema name is specified, the default schema is exported. -# Troubleshooting - -## Exit code not propagated - -If your CI/CD pipeline does not detect command failures, verify that you return the result of `RunWithGraphQLCommandsAsync`. The method now returns an exit code, and not returning it causes the process to always exit with `0`. - -## Schema export fails with errors - -Schema errors surface at startup in v16 due to eager initialization. Fix the schema errors reported in the console output before exporting. - # Next Steps - [Warmup](/docs/hotchocolate/v16/server/warmup) for details on startup behavior and schema initialization. diff --git a/website/src/docs/hotchocolate/v16/server/endpoints.md b/website/src/docs/hotchocolate/v16/server/endpoints.md index bcd5f5939af..728619ded87 100644 --- a/website/src/docs/hotchocolate/v16/server/endpoints.md +++ b/website/src/docs/hotchocolate/v16/server/endpoints.md @@ -454,28 +454,6 @@ builder.Services Per-endpoint `WithOptions` overrides take precedence over schema-level defaults. -# Troubleshooting - -## Nitro not loading in the browser - -Check that the `Tool.Enable` setting is not set to `false`. In production environments, Nitro is often disabled. Set `o.Tool.Enable = true` or conditionally enable it based on the hosting environment. - -## WebSocket requests not working - -Ensure that the ASP.NET Core WebSocket middleware is registered before calling `MapGraphQL()`. Add `app.UseWebSockets()` to your middleware pipeline. - -## Persisted operation returns 400 "Missing operationId" - -Verify that the URL matches the expected pattern. The operation ID must be the first path segment after the persisted operations base path (for example, `/graphql/persisted/abc123`). If `requireOperationName` is `true`, you must also provide the operation name as the second path segment. - -## Large requests rejected before execution - -If large queries or mutations are rejected before reaching the execution engine, the `maxAllowedRequestSize` parameter on `AddGraphQLServer()` is likely too small. Increase it to accommodate your expected payload sizes. - -## Introspection disabled unexpectedly in production - -When `disableDefaultSecurity` is `false` (the default), introspection is automatically turned off in non-development environments. If you need introspection available in production (for example, behind authentication), either set `disableDefaultSecurity: true` and configure security features manually, or explicitly re-enable introspection after `AddGraphQLServer()`. - # Next Steps - [HTTP Transport](/docs/hotchocolate/v16/server/http-transport) for details on request formats, response formats, WebSocket transport, and SSE. diff --git a/website/src/docs/hotchocolate/v16/server/files.md b/website/src/docs/hotchocolate/v16/server/files.md index 5767addb2ff..8e9b2028c05 100644 --- a/website/src/docs/hotchocolate/v16/server/files.md +++ b/website/src/docs/hotchocolate/v16/server/files.md @@ -322,20 +322,6 @@ Serving the file through a dedicated HTTP endpoint makes caching much easier and If you are using a cloud provider for file storage, you are likely already accessing files using a URL and can expose this URL as a `String` field in your graph. If infrastructure for serving files is not in place, you can set up file serving with ASP.NET Core or a dedicated web server like nginx. -# Troubleshooting - -## "Upload scalar can only be used as input" - -The `Upload` scalar is only valid as an input type. You cannot use it as a return type for a field. To expose files in responses, return a URL string pointing to the file instead. - -## File upload fails with 413 or size limit error - -Configure `FormOptions` to increase `MultipartBodyLengthLimit`. Depending on your hosting environment, you may also need to adjust Kestrel or IIS request body size limits. - -## "FileValueNode" not found after upgrading to v16 - -The type was renamed to `UploadValueNode`. Update all references in your custom scalar logic or tests. - # Next Steps - [Arguments](/docs/hotchocolate/v16/building-a-schema/arguments) for details on defining input arguments. diff --git a/website/src/docs/hotchocolate/v16/server/global-state.md b/website/src/docs/hotchocolate/v16/server/global-state.md index 358b17ddc39..234703c35ee 100644 --- a/website/src/docs/hotchocolate/v16/server/global-state.md +++ b/website/src/docs/hotchocolate/v16/server/global-state.md @@ -123,16 +123,6 @@ Take a look at the implementation-first or code-first example. -# Troubleshooting - -## GlobalState value is null or missing - -Verify that the interceptor sets the property before calling `base.OnCreateAsync`. Check that the key matches exactly (keys are case-sensitive). - -## Exception when accessing GlobalState - -The `[GlobalState]` attribute throws an exception when the key does not exist or the value cannot be cast to the target type. If the value might be absent, make the parameter nullable (for example, `string?`). - # Next Steps - [Interceptors](/docs/hotchocolate/v16/server/interceptors) for initializing state before request execution. diff --git a/website/src/docs/hotchocolate/v16/server/http-transport.md b/website/src/docs/hotchocolate/v16/server/http-transport.md index b11bc5fea08..7a1c1525aeb 100644 --- a/website/src/docs/hotchocolate/v16/server/http-transport.md +++ b/website/src/docs/hotchocolate/v16/server/http-transport.md @@ -485,36 +485,6 @@ app.MapGraphQL().WithOptions(o => If a request is rejected because it lacks the required preflight header, the server responds with a `400 Bad Request` status. -# Troubleshooting - -## Clients receive v0.2 format unexpectedly - -In v16, the default incremental delivery format changed from v0.1 to v0.2. If your clients expect v0.1, either update the clients to send `incrementalSpec=v0.1` in the `Accept` header, or change the server default to `IncrementalDeliveryFormat.Version_0_1`. - -## "Unexpected Content-Type" errors on legacy clients - -If your clients expect `application/json` responses and cannot handle `application/graphql-response+json`, configure `HttpTransportVersion.Legacy` in the response formatter options. - -## WebSocket connections fail or are not upgraded - -Verify that `app.UseWebSockets()` is called before `app.MapGraphQL()` in your middleware pipeline. Without the ASP.NET Core WebSocket middleware registered, WebSocket upgrade requests are ignored and fall through to the HTTP handler, which returns a `404` response. - -## WebSocket connections drop after a period of inactivity - -The default keep-alive interval is 5 seconds. If your infrastructure (load balancers, proxies) has shorter idle timeouts, decrease `KeepAliveInterval`. If you disabled keep-alive by setting it to `null`, re-enable it or configure your infrastructure to allow long-lived connections. - -## Client times out during connection initialization - -The server closes the WebSocket if the client does not send `connection_init` within 10 seconds (the default `ConnectionInitializationTimeout`). If your client needs more time (for example, to complete authentication), increase the timeout via `ModifyServerOptions`. - -## SSE connections are closed prematurely by a proxy - -Some reverse proxies and CDNs buffer SSE responses or enforce short timeouts on streaming connections. Configure your proxy to disable response buffering for the GraphQL endpoint and set a sufficiently long read timeout. - -## Multipart requests are rejected with 400 - -If `EnforceMultipartRequestsPreflightHeader` is `true` (the default), the client must include a preflight header such as `GraphQL-Preflight: 1` with multipart requests. Check that your client sends this header. - # Next Steps - [Endpoints](/docs/hotchocolate/v16/server/endpoints) for configuring the GraphQL middleware and per-endpoint options. diff --git a/website/src/docs/hotchocolate/v16/server/instrumentation.md b/website/src/docs/hotchocolate/v16/server/instrumentation.md index 3f0e8744f8b..3814d6fd701 100644 --- a/website/src/docs/hotchocolate/v16/server/instrumentation.md +++ b/website/src/docs/hotchocolate/v16/server/instrumentation.md @@ -418,20 +418,6 @@ The following enricher methods are available: ![Jaeger](../../../shared/jaeger4.png) -# Troubleshooting - -## No spans appear in the tracing backend - -Verify that you have called both `AddInstrumentation()` on the GraphQL server configuration and `AddHotChocolateInstrumentation()` on the OpenTelemetry tracing builder. Both are required. - -## Missing field-level spans - -Field-level spans are disabled by default because they add overhead for every resolver. Enable them by setting `o.Scopes = ActivityScopes.All` in the `AddInstrumentation` options. Alternatively, override `EnableResolveFieldValue` in a custom `ExecutionDiagnosticEventListener`. - -## Custom enricher not called - -Ensure the enricher is registered as a singleton (`AddSingleton()`) and cross-registered in the schema services with `AddApplicationService()`. - # Next Steps - [HTTP Transport](/docs/hotchocolate/v16/server/http-transport) for details on streaming transports and response formatting. diff --git a/website/src/docs/hotchocolate/v16/server/interceptors.md b/website/src/docs/hotchocolate/v16/server/interceptors.md index ae90a337bcd..47990a41c15 100644 --- a/website/src/docs/hotchocolate/v16/server/interceptors.md +++ b/website/src/docs/hotchocolate/v16/server/interceptors.md @@ -340,16 +340,6 @@ If you have disabled introspection globally, `AllowIntrospection` lets you enabl requestBuilder.AllowIntrospection(); ``` -# Troubleshooting - -## Interceptor not being called - -Verify that you registered the interceptor using `AddHttpRequestInterceptor()` or `AddSocketSessionInterceptor()` on the `IRequestExecutorBuilder`. If the interceptor depends on application services, you may need to register them with `AddApplicationService()`. - -## Missing ClaimsPrincipal in resolvers - -Always call `base.OnCreateAsync` (for HTTP) or `base.OnRequestAsync` (for WebSocket) in your interceptor. The base implementation is responsible for setting up the `ClaimsPrincipal` and other global state. - # Next Steps - [Global State](/docs/hotchocolate/v16/server/global-state) for sharing per-request data between resolvers. diff --git a/website/src/docs/hotchocolate/v16/server/warmup.md b/website/src/docs/hotchocolate/v16/server/warmup.md index c5d2ee480e9..70599de4c38 100644 --- a/website/src/docs/hotchocolate/v16/server/warmup.md +++ b/website/src/docs/hotchocolate/v16/server/warmup.md @@ -154,20 +154,6 @@ builder.Services With lazy initialization enabled, the schema is constructed when it is first needed, either when a request is executed or when the schema is otherwise accessed. Depending on the size of your schema and the configured warmup tasks, this causes initial requests to run longer than they would with eager initialization. -# Troubleshooting - -## Warmup task runs but cache misses still occur - -The operation name is part of the cache key. If your client sends an operation name that differs from the one in your warmup request (or omits it when the warmup includes one), the cache lookup will miss. Ensure the warmup request matches what the client sends. - -## Server takes too long to start - -If your warmup tasks execute heavy operations, consider marking them as warmup requests with `MarkAsWarmupRequest()`. This skips the actual execution of the operation while still populating the document and operation caches. - -## Schema errors surface at startup - -This is the expected behavior of eager initialization. Fix the schema errors before proceeding. If you need to defer errors to runtime (not recommended), set `options.LazyInitialization = true`. - # Next Steps - [Instrumentation](/docs/hotchocolate/v16/server/instrumentation) for monitoring request execution and tracing.