[website] Removed Troubleshooting Sections

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

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

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<T>()` on `IServiceCollection`. If you are using the split service provider model in v16, you may need to register the filter's dependencies using `AddApplicationService<T>()` 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

website/src/docs/hotchocolate/v16/api-reference/executable.md

@@ -113,14 +113,6 @@ public class EntityFrameworkExecutable<T> : QueryableExecutable<T>
 }
 ```
 
-# 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

website/src/docs/hotchocolate/v16/api-reference/extending-filtering.md

@@ -285,17 +285,6 @@ builder.Services
                     y => y.AddFieldHandler<QueryableStringInvariantEqualsHandler>()))));
 ```
 
-# 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<T>` 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

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

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

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

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).

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<T>()` 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).

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).

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).

website/src/docs/hotchocolate/v16/building-a-schema/enums.md

@@ -206,20 +206,6 @@ public class UserRoleType : EnumType<string>
 
 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<T>` and the enum does not appear in the schema, verify you have registered it with `.AddType<UserRoleType>()`. Code-first enums require explicit registration.
-
 # Next Steps
 
 - **Need to define output types?** See [Object Types](/docs/hotchocolate/v16/defining-a-schema/object-types).

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<T>()`. Unlike regular types, extensions require explicit registration.
-
-## Source generator extension not discovered
-
-When using `[ExtendObjectType<T>]` 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).

website/src/docs/hotchocolate/v16/building-a-schema/input-object-types.md

@@ -259,20 +259,6 @@ public class PetInputType : InputObjectType<PetInput>
 
 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<T>()`.
-
-## 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<T>` field still required
-
-When using `Optional<T>` 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).

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<T>()`. 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).

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<T>` 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<User?>`).
-
-## IQueryable not executing
-
-When returning `IQueryable<T>`, 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).

website/src/docs/hotchocolate/v16/building-a-schema/mutations.md

@@ -406,20 +406,6 @@ builder.Services
     .AddTransactionScopeHandler<CustomTransactionScopeHandler>();
 ```
 
-# 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).

website/src/docs/hotchocolate/v16/building-a-schema/non-null.md

@@ -151,20 +151,6 @@ public class BookType : ObjectType<Book>
 
 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 `<Nullable>enable</Nullable>`.
-
-## 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).