Troubleshooting

No code is generated after build

Checklist:

1. Verify the manifest file is registered as AdditionalFiles in .csproj (Mode A) or the domain assembly is referenced with ReferenceOutputAssembly="true" (Mode B)
2. Check the manifest file name ends with manifest.json or PragmaticManifest.json
3. Verify the manifest has at least one entry in "endpoints" — empty endpoint arrays produce no output
4. Check PragmaticClientBoundaries property (if set) matches the operationId prefixes in the manifest
5. Look in obj/Debug/net10.0/ for *.g.cs files or PragmaticClient.*.Error.g.cs error markers

Build succeeds but generated types are not visible in IDE

Cause: IDE may not have refreshed its analyzer cache.

Fix:

• Restart the IDE or reload the solution
• In Visual Studio: close and reopen the solution, or run dotnet build from CLI first
• In Rider: invalidate caches (File > Invalidate Caches)
• Verify the SG package has OutputItemType="Analyzer" in the project reference

Error marker file generated instead of client code

If you see a file like PragmaticClient.Showcase_Booking.Error.g.cs containing:

// Client SG error: <message>

This means the generator encountered an exception while processing the manifest. Common causes:

• Malformed JSON in the manifest
• Missing required fields (endpoints array)
• Invalid property types that cause deserialization failures

Fix: Validate the manifest JSON, for example with System.Text.Json:

dotnet script -e "System.Text.Json.JsonDocument.Parse(File.ReadAllText(\"PragmaticManifest.json\"))"

Result<object, IError> instead of expected typed response

Cause: The response type in the manifest is either:

• A generic type like PagedResult<GuestDto> (generics map to object currently)
• A type not declared in the manifest’s types array
• A type with a fully-qualified name that does not match any known CLR type

Fix:

• For entity/DTO types: ensure they appear in the types array with "kind": "entity" or "kind": "dto" and a simpleName
• For generic types: this is a known limitation; manual deserialization is needed

PragmaticClientException thrown at runtime

PragmaticClientException is thrown when the HTTP response cannot be interpreted at all (not even as a ProblemDetails error). This typically means:

• The server returned HTML (e.g., a 502 gateway error page)
• The response body is completely empty and not JSON
• Network-level errors that produce non-JSON responses

The generated MapErrorAsync method handles this gracefully by catching JSON parse failures and returning a generic ApiError. A PragmaticClientException should only occur in truly unexpected scenarios outside the normal error mapping flow.

DI registration method not found

Symptom: AddBookingClient method does not exist.

Checklist:

1. Verify the manifest "assembly" field is set — the boundary name is derived from the last segment (e.g., "Showcase.Booking" produces AddBookingClient)
2. Ensure the SG package is correctly referenced as an analyzer
3. Check that Microsoft.Extensions.DependencyInjection is available (comes transitively from most ASP.NET Core / Blazor templates)

Error types not matching at runtime

Symptom: result.Error is always ApiError and never a typed error like ConflictError.

Cause: The error code in the ProblemDetails response does not match the errorCode in the manifest.

Debug steps:

1. Inspect the raw HTTP response to see the actual ProblemDetails code value
2. Compare it with the errorCode values in the manifest’s types array
3. The match is case-sensitive and exact — "CONFLICT" does not match "conflict"

Duplicate DTO names across manifests

If two manifests define the same simpleName for a type (e.g., both have a GuestDto), the generator processes them independently because each manifest produces code in the same client namespace. This causes CS0101 (duplicate type) compilation errors.

Fix: Use PragmaticClientBoundaries to limit which boundaries are generated, or separate client projects per domain.

Mode B: Domain assembly not providing manifest

Checklist:

1. The domain assembly must have [PragmaticMetadata] attributes with category 18 (Manifest)
2. This is generated by Pragmatic.SourceGenerator — ensure the domain project references it
3. The domain assembly must be referenced with ReferenceOutputAssembly="true" (default for ProjectReference)
4. Build the domain project first: dotnet build the server project so the metadata attributes are compiled

Generated code has compilation errors

Common causes and fixes:

Error	Cause	Fix
CS0246 HttpClient not found	Missing System.Net.Http	Add <FrameworkReference Include="Microsoft.AspNetCore.App" /> or ensure net10.0 target
CS0246 IServiceCollection not found	Missing DI abstractions	Add Microsoft.Extensions.DependencyInjection.Abstractions package
CS0246 Result not found	Missing Pragmatic.Result	Add Pragmatic.Result package reference
CS0246 ApiError not found	Missing Pragmatic.Client	Add Pragmatic.Client package reference

Manifest versioning

The manifest uses "$schema": "pragmatic-manifest/v1" to identify its format version. The current generator only supports v1. If the server upgrades its manifest format, ensure the generator package is updated to match.