diff --git a/.chronus/changes/java-diagnostic-docs-2026-08-04-16-55-00.md b/.chronus/changes/java-diagnostic-docs-2026-08-04-16-55-00.md
new file mode 100644
index 00000000000..620f6f34ee7
--- /dev/null
+++ b/.chronus/changes/java-diagnostic-docs-2026-08-04-16-55-00.md
@@ -0,0 +1,7 @@
+---
+changeKind: internal
+packages:
+  - "@typespec/http-client-java"
+---
+
+Add reference documentation for Java emitter diagnostics.
diff --git a/packages/http-client-java/emitter/src/diagnostics/auth-scheme-not-supported.md b/packages/http-client-java/emitter/src/diagnostics/auth-scheme-not-supported.md
new file mode 100644
index 00000000000..e27d74059ec
--- /dev/null
+++ b/packages/http-client-java/emitter/src/diagnostics/auth-scheme-not-supported.md
@@ -0,0 +1,57 @@
+This diagnostic is issued when an authentication scheme cannot be represented by the selected Java client flavor.
+
+## Impact
+
+The generated client may omit the scheme or fall back to a less specific credential type.
+
+## ❌ Incorrect Usage
+
+### API key outside a header
+
+```typespec
+@service
+@useAuth(ApiKeyAuth<ApiKeyLocation.query, "api-key">)
+namespace Contoso;
+```
+
+### Basic authentication for an Azure client
+
+```typespec
+@service
+@useAuth(BasicAuth)
+namespace Contoso;
+```
+
+```yaml
+options:
+  "@typespec/http-client-java":
+    flavor: azure
+```
+
+## Diagnostic Message
+
+The message identifies the unsupported scheme, location, or flavor. For example:
+
+```text
+ApiKey auth is currently only supported for ApiKeyLocation.header.
+```
+
+## ✅ How to Fix
+
+Use OAuth2 authentication.
+
+```typespec
+@service
+@useAuth(OAuth2Auth<[OAuthFlow]>)
+namespace Contoso;
+
+model OAuthFlow {
+  type: OAuth2FlowType.clientCredentials;
+  tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token";
+  scopes: ["https://contoso.com/.default"];
+}
+```
+
+## Suppression
+
+Do not suppress this warning unless custom code will provide the intended authentication behavior.
diff --git a/packages/http-client-java/emitter/src/diagnostics/client-required-false.md b/packages/http-client-java/emitter/src/diagnostics/client-required-false.md
new file mode 100644
index 00000000000..55e051579f5
--- /dev/null
+++ b/packages/http-client-java/emitter/src/diagnostics/client-required-false.md
@@ -0,0 +1,37 @@
+This diagnostic is issued when the Java `clientRequired` client option is explicitly set to `false`.
+
+## Impact
+
+Java client generation fails because the option only supports promoting a parameter to required; it cannot make a required parameter optional.
+
+## ❌ Incorrect Usage
+
+```typespec
+model ReadOptions {
+  @query filter: string;
+}
+
+op read(...ReadOptions): void;
+
+@@clientOption(ReadOptions.filter, "clientRequired", false, "java");
+```
+
+## Diagnostic Message
+
+```text
+Client option 'clientRequired' can only be set to 'true'.
+```
+
+## ✅ How to Fix
+
+Remove the client option, or set it to `true` for an optional TypeSpec parameter that must be required in the Java client.
+
+```typespec
+model ReadOptions {
+  @query filter?: string;
+}
+
+op read(...ReadOptions): void;
+
+@@clientOption(ReadOptions.filter, "clientRequired", true, "java");
+```
diff --git a/packages/http-client-java/emitter/src/diagnostics/constant-header-in-response-removed.md b/packages/http-client-java/emitter/src/diagnostics/constant-header-in-response-removed.md
new file mode 100644
index 00000000000..24cb05ea3b3
--- /dev/null
+++ b/packages/http-client-java/emitter/src/diagnostics/constant-header-in-response-removed.md
@@ -0,0 +1,29 @@
+This diagnostic is issued when a response content-type header has a constant value and the Java emitter removes it from the generated response-header model.
+
+## Impact
+
+The constant header is not generated as a property in the response-header model because its value cannot vary.
+
+## Example Usage
+
+```typespec
+op read(): {
+  @statusCode statusCode: 200;
+  @header contentType: "application/json";
+  @body body: Widget;
+};
+```
+
+## Diagnostic Message
+
+```text
+Constant header 'content-type' is removed from response headers.
+```
+
+## How to Address
+
+No change is required. The TypeSpec definition is valid, and the warning only explains why the generated response-header model does not contain a property for this header.
+
+## Suppression
+
+It is safe to ignore or suppress this warning when the constant header does not need to be exposed as a property.
diff --git a/packages/http-client-java/emitter/src/diagnostics/convenience-api-not-generated.md b/packages/http-client-java/emitter/src/diagnostics/convenience-api-not-generated.md
new file mode 100644
index 00000000000..801b3fac441
--- /dev/null
+++ b/packages/http-client-java/emitter/src/diagnostics/convenience-api-not-generated.md
@@ -0,0 +1,51 @@
+This diagnostic is issued when the Java emitter cannot form a safe convenience-method signature.
+
+## Impact
+
+The protocol API remains available, but the convenience API is omitted for the operation.
+
+## Multiple Content Types
+
+```typespec
+@post
+op upload(@body data: bytes, @header contentType: "application/octet-stream" | "image/png"): void;
+```
+
+```yaml
+options:
+  "@typespec/http-client-java":
+    flavor: azure
+```
+
+This TypeSpec definition is valid. Customize the generated Java library to add a convenience API with the appropriate method signature and behavior for the operation. The generated protocol API can be used as the underlying implementation.
+
+## JSON Merge Patch Without Stream-Style Serialization
+
+```typespec
+@patch
+op update(@header contentType: "application/merge-patch+json", @body body: WidgetPatch): void;
+```
+
+```yaml
+options:
+  "@typespec/http-client-java":
+    flavor: azure
+    stream-style-serialization: false
+```
+
+Enable stream-style serialization:
+
+```yaml
+options:
+  "@typespec/http-client-java":
+    flavor: azure
+    stream-style-serialization: true
+```
+
+## Diagnostic Message
+
+The message identifies either multiple content types or JSON merge patch as the reason the convenience API was not generated.
+
+## Suppression
+
+For multiple content types, suppress the warning after adding the required convenience API customization, or when a protocol-only API surface is intentional. Do not suppress the JSON merge patch warning; enable stream-style serialization instead.
diff --git a/packages/http-client-java/emitter/src/diagnostics/empty-name.md b/packages/http-client-java/emitter/src/diagnostics/empty-name.md
new file mode 100644
index 00000000000..61a1772deaa
--- /dev/null
+++ b/packages/http-client-java/emitter/src/diagnostics/empty-name.md
@@ -0,0 +1,29 @@
+This diagnostic is issued when TCGC supplies a model without a usable generated name.
+
+## Impact
+
+Java client generation stops because every emitted Java model requires a class name.
+
+## ❌ Incorrect Usage
+
+The diagnostic is generally caused by an anonymous or synthesized model shape for which the SDK model did not produce a name. There is no single TypeSpec construct that always triggers it.
+
+## Diagnostic Message
+
+```text
+Name from TCGC is empty.
+```
+
+## ✅ How to Fix
+
+Give anonymous request or response shapes an explicit model name and reference that model from the operation.
+
+```typespec
+model WidgetResponse {
+  value: string;
+}
+
+op getWidget(): WidgetResponse;
+```
+
+If all involved models are already named, update the emitter dependencies and report a minimal reproduction.
diff --git a/packages/http-client-java/emitter/src/diagnostics/header-parameter-format-not-supported.md b/packages/http-client-java/emitter/src/diagnostics/header-parameter-format-not-supported.md
new file mode 100644
index 00000000000..b64fb4a3460
--- /dev/null
+++ b/packages/http-client-java/emitter/src/diagnostics/header-parameter-format-not-supported.md
@@ -0,0 +1,33 @@
+This diagnostic is issued when an array-valued header uses any collection format other than CSV. The Java emitter supports only comma-delimited arrays for header parameters.
+
+## Impact
+
+The requested header serialization format is ignored, which can produce a request that does not match the service contract.
+
+## ❌ Incorrect Usage
+
+```typespec
+op read(
+  @header
+  @encode(ArrayEncoding.pipeDelimited)
+  values: string[],
+): void;
+```
+
+## Diagnostic Message
+
+```text
+Header parameter format '<format>' is not supported.
+```
+
+## ✅ How to Fix
+
+Use the default comma-delimited header representation.
+
+```typespec
+op read(@header values: string[]): void;
+```
+
+## Suppression
+
+This warning should not be suppressed. Change the service contract or header encoding to CSV.
diff --git a/packages/http-client-java/emitter/src/diagnostics/invalid-api-version.md b/packages/http-client-java/emitter/src/diagnostics/invalid-api-version.md
new file mode 100644
index 00000000000..5231483d650
--- /dev/null
+++ b/packages/http-client-java/emitter/src/diagnostics/invalid-api-version.md
@@ -0,0 +1,40 @@
+This diagnostic is issued when the `api-version` emitter option is neither a declared service version nor `latest` or `all`.
+
+## Impact
+
+The requested API-version projection cannot be selected, so Java client generation fails.
+
+## ❌ Incorrect Usage
+
+```typespec
+@service
+@versioned(Versions)
+namespace Contoso;
+
+enum Versions {
+  v1,
+  v2,
+}
+```
+
+```yaml
+options:
+  "@typespec/http-client-java":
+    api-version: v3
+```
+
+## Diagnostic Message
+
+```text
+Invalid api-version option: 'v3'. The value should be an api-version, 'latest', or 'all'.
+```
+
+## ✅ How to Fix
+
+Use a version declared by the service, or use `latest` or `all`.
+
+```yaml
+options:
+  "@typespec/http-client-java":
+    api-version: v2
+```
diff --git a/packages/http-client-java/emitter/src/diagnostics/invalid-java-namespace.md b/packages/http-client-java/emitter/src/diagnostics/invalid-java-namespace.md
new file mode 100644
index 00000000000..c1a23af4610
--- /dev/null
+++ b/packages/http-client-java/emitter/src/diagnostics/invalid-java-namespace.md
@@ -0,0 +1,33 @@
+This diagnostic is issued when a generated Java package segment is a reserved Java keyword.
+
+## Impact
+
+The emitter appends `namespace` to the reserved package segment, so the generated package differs from the requested namespace.
+
+## ❌ Incorrect Usage
+
+```typespec
+@service
+namespace Contoso.Public;
+```
+
+The derived Java namespace contains the reserved keyword `public`.
+
+## Diagnostic Message
+
+```text
+Namespace 'contoso.public' contains reserved Java keywords, replaced it with 'contoso.publicnamespace'.
+```
+
+## ✅ How to Fix
+
+Rename the TypeSpec namespace or configure a Java namespace that does not contain Java keywords.
+
+```typespec
+@service
+namespace Contoso.PublicApi;
+```
+
+## Suppression
+
+Suppress the warning only when the adjusted package name is intentionally accepted.
diff --git a/packages/http-client-java/emitter/src/diagnostics/invalid-java-sdk-dependency.md b/packages/http-client-java/emitter/src/diagnostics/invalid-java-sdk-dependency.md
new file mode 100644
index 00000000000..0361b10900c
--- /dev/null
+++ b/packages/http-client-java/emitter/src/diagnostics/invalid-java-sdk-dependency.md
@@ -0,0 +1,27 @@
+This diagnostic is issued when the Java emitter cannot find a supported JDK, Java runtime, or Apache Maven installation.
+
+## Impact
+
+Java client generation cannot run because the generator process depends on these tools.
+
+## ❌ Incorrect Usage
+
+The emitter is run in an environment where `javac`, `java`, or `mvn` is missing from `PATH`, or where Java is older than the required version.
+
+## Diagnostic Message
+
+The message identifies the missing tool or unsupported Java version, for example:
+
+```text
+Java Development Kit (JDK) is not found in PATH. Please install JDK 17 or above.
+```
+
+## ✅ How to Fix
+
+Install JDK 17 or later and Apache Maven, add their executable directories to `PATH`, and verify:
+
+```shell
+javac -version
+java -version
+mvn -version
+```
diff --git a/packages/http-client-java/emitter/src/diagnostics/multiple-server-not-supported.md b/packages/http-client-java/emitter/src/diagnostics/multiple-server-not-supported.md
new file mode 100644
index 00000000000..eb126211cfe
--- /dev/null
+++ b/packages/http-client-java/emitter/src/diagnostics/multiple-server-not-supported.md
@@ -0,0 +1,47 @@
+This diagnostic is issued when a service declares multiple alternative ways to specify its endpoint.
+
+## Impact
+
+The service definition is valid, but the Java emitter currently supports only one server definition when constructing the client endpoint.
+
+## Valid Usage
+
+```typespec
+@service
+@server(
+  "https://{region}.example.com",
+  "Regional",
+  {
+    region: string,
+  }
+)
+@server("https://example.com", "Global")
+@server("http://localhost:3000", "Local")
+namespace Contoso {
+  op read(): string;
+}
+```
+
+## Diagnostic Message
+
+```text
+Multiple server on client is not supported.
+```
+
+## How to Address
+
+If the service supports multiple endpoint forms, no change to the service contract is required. Until the Java emitter supports this pattern, select one server definition for generation and customize the Java library to expose the additional endpoint forms.
+
+```typespec
+@service
+@server(
+  "https://{region}.example.com",
+  "Service endpoint",
+  {
+    region: string,
+  }
+)
+namespace Contoso {
+  op read(): string;
+}
+```
diff --git a/packages/http-client-java/emitter/src/diagnostics/no-service.md b/packages/http-client-java/emitter/src/diagnostics/no-service.md
new file mode 100644
index 00000000000..84b74efde97
--- /dev/null
+++ b/packages/http-client-java/emitter/src/diagnostics/no-service.md
@@ -0,0 +1,42 @@
+This diagnostic is issued when the TypeSpec program does not contain a namespace marked with `@service`.
+
+## Impact
+
+No Java client is generated because the emitter cannot identify the service root. Models with explicit usage and access metadata can still be generated.
+
+## Valid Model-Only Usage
+
+```typespec
+import "@azure-tools/typespec-client-generator-core";
+
+using Azure.ClientGenerator.Core;
+
+@access(Access.public)
+@usage(Usage.input | Usage.output)
+model Widget {
+  name: string;
+}
+```
+
+This generates the public `Widget` Java model without generating a service client. The warning is expected for this use case.
+
+## Diagnostic Message
+
+```text
+No service found in this TypeSpec. Client will not be generated.
+```
+
+## ✅ How to Fix
+
+If a Java client is intended, mark the service namespace with `@service` and define its operations.
+
+```typespec
+@service
+namespace Contoso {
+  op ping(): void;
+}
+```
+
+## Suppression
+
+It is safe to suppress this warning when the TypeSpec intentionally generates only model classes.
diff --git a/packages/http-client-java/emitter/src/diagnostics/protocol-api-not-generated.md b/packages/http-client-java/emitter/src/diagnostics/protocol-api-not-generated.md
new file mode 100644
index 00000000000..944110a2a8b
--- /dev/null
+++ b/packages/http-client-java/emitter/src/diagnostics/protocol-api-not-generated.md
@@ -0,0 +1,30 @@
+This diagnostic is issued when an Azure-flavored multipart operation would produce a protocol API that is not usable with the generated request shape.
+
+## Impact
+
+The convenience API is generated, but the protocol API is omitted for the operation.
+
+## Example Usage
+
+```typespec
+model UploadForm {
+  file: HttpPart<bytes>;
+}
+
+@post
+op upload(@header contentType: "multipart/form-data", @multipartBody body: UploadForm): void;
+```
+
+## Diagnostic Message
+
+```text
+Operation 'upload' is of content-type 'multipart/form-data'. Protocol API is not usable and hence not generated.
+```
+
+## How to Address
+
+No change is required. Use the generated convenience API for the multipart operation.
+
+## Suppression
+
+It is safe to ignore or suppress this notification when the generated convenience API is sufficient.
diff --git a/packages/http-client-java/emitter/src/diagnostics/response-headers-as-model-with-body.md b/packages/http-client-java/emitter/src/diagnostics/response-headers-as-model-with-body.md
new file mode 100644
index 00000000000..30fe27f9e1c
--- /dev/null
+++ b/packages/http-client-java/emitter/src/diagnostics/response-headers-as-model-with-body.md
@@ -0,0 +1,36 @@
+This diagnostic is issued when `responseHeadersAsModel` is enabled for an operation that also returns a response body.
+
+## Impact
+
+Java client generation fails because the option is only defined for returning significant response headers from bodyless operations.
+
+## ❌ Incorrect Usage
+
+```typespec
+op getWidget(): {
+  @statusCode statusCode: 200;
+  @header eTag: string;
+  @body body: Widget;
+};
+
+@@clientOption(getWidget, "responseHeadersAsModel", true, "java");
+```
+
+## Diagnostic Message
+
+```text
+Client option 'responseHeadersAsModel' cannot be used on operation 'getWidget', because it has a response body.
+```
+
+## ✅ How to Fix
+
+Remove the option for operations with response bodies. Use it only when the response contains significant headers and no body.
+
+```typespec
+op getWidgetMetadata(): {
+  @statusCode statusCode: 200;
+  @header eTag: string;
+};
+
+@@clientOption(getWidgetMetadata, "responseHeadersAsModel", true, "java");
+```
diff --git a/packages/http-client-java/emitter/src/diagnostics/spread-json-merge-patch-payload-not-supported.md b/packages/http-client-java/emitter/src/diagnostics/spread-json-merge-patch-payload-not-supported.md
new file mode 100644
index 00000000000..ce0945776e4
--- /dev/null
+++ b/packages/http-client-java/emitter/src/diagnostics/spread-json-merge-patch-payload-not-supported.md
@@ -0,0 +1,35 @@
+This diagnostic is issued when an operation spreads a JSON merge-patch body into method parameters.
+
+## Impact
+
+The body is kept as a model parameter because separate Java parameters cannot distinguish an omitted property from a property explicitly set to `null`.
+
+## ❌ Incorrect Usage
+
+```typespec
+model WidgetPatch {
+  name?: string | null;
+}
+
+@patch
+op update(@header contentType: "application/merge-patch+json", ...WidgetPatch): void;
+```
+
+## Diagnostic Message
+
+```text
+Spread JSON merge-patch payload is not supported.
+```
+
+## ✅ How to Fix
+
+Pass the patch model as the request body instead of spreading its properties.
+
+```typespec
+@patch
+op update(@header contentType: "application/merge-patch+json", @body body: WidgetPatch): void;
+```
+
+## Suppression
+
+This warning should not be suppressed because the generated method shape intentionally changes to preserve merge-patch semantics.
diff --git a/packages/http-client-java/emitter/src/diagnostics/type-not-supported-on-text-plain.md b/packages/http-client-java/emitter/src/diagnostics/type-not-supported-on-text-plain.md
new file mode 100644
index 00000000000..e69eec5e1e9
--- /dev/null
+++ b/packages/http-client-java/emitter/src/diagnostics/type-not-supported-on-text-plain.md
@@ -0,0 +1,36 @@
+This diagnostic is issued when an operation uses an enum request or response body with `text/plain`.
+
+## Impact
+
+The emitter substitutes `String` for the unsupported Java type on the request or response body.
+
+## ❌ Incorrect Usage
+
+```typespec
+enum Color {
+  red,
+  blue,
+}
+
+@post
+op setColor(@header contentType: "text/plain", @body color: Color): void;
+```
+
+## Diagnostic Message
+
+```text
+Complex SDK type is not supported for "text/plain" content-type. Emitter would use string type on 'setColor' request body.
+```
+
+## ✅ How to Fix
+
+Use `string` for a text payload, or use a structured content type such as `application/json` when the SDK type should remain strongly typed.
+
+```typespec
+@post
+op setColor(@header contentType: "text/plain", @body color: string): void;
+```
+
+## Suppression
+
+Suppress the warning only when the generated `String` API is the intended contract.
diff --git a/packages/http-client-java/emitter/src/diagnostics/unknown-encode.md b/packages/http-client-java/emitter/src/diagnostics/unknown-encode.md
new file mode 100644
index 00000000000..350b7e9754a
--- /dev/null
+++ b/packages/http-client-java/emitter/src/diagnostics/unknown-encode.md
@@ -0,0 +1,31 @@
+This diagnostic is issued when a bytes, duration, or date-time type uses an encoding that the Java emitter does not recognize.
+
+## Impact
+
+The emitter falls back to the wire type or a string representation, so the generated Java type may not preserve the intended encoding.
+
+## ❌ Incorrect Usage
+
+```typespec
+@encode("custom-datetime")
+scalar CustomDateTime extends utcDateTime;
+```
+
+## Diagnostic Message
+
+```text
+Encode 'custom-datetime' is not supported.
+```
+
+## ✅ How to Fix
+
+Use a standard encoding supported by the corresponding TypeSpec scalar.
+
+```typespec
+@encode(DateTimeKnownEncoding.rfc3339)
+scalar CustomDateTime extends utcDateTime;
+```
+
+## Suppression
+
+Suppress this warning only when the fallback Java representation and wire format have been verified, or when the generated Java library will be customized to implement the intended encoding.
diff --git a/packages/http-client-java/emitter/src/diagnostics/unrecognized-type.md b/packages/http-client-java/emitter/src/diagnostics/unrecognized-type.md
new file mode 100644
index 00000000000..8862d1078da
--- /dev/null
+++ b/packages/http-client-java/emitter/src/diagnostics/unrecognized-type.md
@@ -0,0 +1,29 @@
+This diagnostic is issued when the Java emitter receives an SDK type kind that it cannot map to a Java schema. Specialized messages identify unsupported union or multipart property kinds.
+
+## Impact
+
+Java client generation stops because the emitter cannot determine a safe Java representation.
+
+## ❌ Incorrect Usage
+
+This usually indicates an unsupported TypeSpec shape or a version mismatch between the Java emitter and `@azure-tools/typespec-client-generator-core`. It can also occur when a union or multipart model contains a type kind that the emitter does not support.
+
+## Diagnostic Message
+
+Messages include:
+
+```text
+Unrecognized type, kind '<kind>'. Updating the version of the emitter may resolve this issue.
+```
+
+```text
+Unrecognized type for Union, kind '<kind>'.
+```
+
+```text
+Unrecognized type for multipart form data, kind '<kind>'.
+```
+
+## ✅ How to Fix
+
+Update the Java emitter and TypeSpec dependencies together. If the error identifies a union or multipart property, replace the unsupported member with a supported scalar, model, array, or file type. If the kind should be supported, report an emitter issue with a minimal TypeSpec reproduction.
diff --git a/packages/http-client-java/emitter/src/lib.ts b/packages/http-client-java/emitter/src/lib.ts
index 9074269eda4..73a4a582612 100644
--- a/packages/http-client-java/emitter/src/lib.ts
+++ b/packages/http-client-java/emitter/src/lib.ts
@@ -1,5 +1,18 @@
 import { createTypeSpecLibrary, paramMessage } from "@typespec/compiler";
-import { EmitterOptionsSchema, LIB_NAME } from "./options.js";
+import { DIAGNOSTIC_DOCS_BASE_URL, EmitterOptionsSchema, LIB_NAME } from "./options.js";
+
+/**
+ * Build the source documentation reference and published URL for a diagnostic.
+ */
+function doc(code: string) {
+  return {
+    docs: {
+      kind: "file-ref" as const,
+      path: `emitter/src/diagnostics/${code}.md`,
+    },
+    url: `${DIAGNOSTIC_DOCS_BASE_URL}/${code}`,
+  };
+}
 
 export const $lib = createTypeSpecLibrary({
   name: LIB_NAME,
@@ -18,6 +31,7 @@ export const $lib = createTypeSpecLibrary({
       },
     },
     "invalid-java-sdk-dependency": {
+      ...doc("invalid-java-sdk-dependency"),
       severity: "error",
       messages: {
         default:
@@ -30,18 +44,21 @@ export const $lib = createTypeSpecLibrary({
       },
     },
     "multiple-server-not-supported": {
+      ...doc("multiple-server-not-supported"),
       severity: "error",
       messages: {
         default: "Multiple server on client is not supported.",
       },
     },
     "invalid-api-version": {
+      ...doc("invalid-api-version"),
       severity: "error",
       messages: {
         default: paramMessage`Invalid api-version option: '${"apiVersion"}'. The value should be an api-version, 'latest', or 'all'.`,
       },
     },
     "unrecognized-type": {
+      ...doc("unrecognized-type"),
       severity: "error",
       messages: {
         default: paramMessage`Unrecognized type, kind '${"typeKind"}'. Updating the version of the emitter may resolve this issue.`,
@@ -50,6 +67,7 @@ export const $lib = createTypeSpecLibrary({
       },
     },
     "empty-name": {
+      ...doc("empty-name"),
       severity: "error",
       messages: {
         default: "Name from TCGC is empty.",
@@ -64,12 +82,14 @@ export const $lib = createTypeSpecLibrary({
       },
     },
     "no-service": {
+      ...doc("no-service"),
       severity: "warning",
       messages: {
         default: "No service found in this TypeSpec. Client will not be generated.",
       },
     },
     "auth-scheme-not-supported": {
+      ...doc("auth-scheme-not-supported"),
       severity: "warning",
       messages: {
         oauth2Unbranded:
@@ -79,12 +99,14 @@ export const $lib = createTypeSpecLibrary({
       },
     },
     "protocol-api-not-generated": {
+      ...doc("protocol-api-not-generated"),
       severity: "warning",
       messages: {
         multipartFormData: paramMessage`Operation '${"operationName"}' is of content-type 'multipart/form-data'. Protocol API is not usable and hence not generated.`,
       },
     },
     "convenience-api-not-generated": {
+      ...doc("convenience-api-not-generated"),
       severity: "warning",
       messages: {
         multipleContentType: paramMessage`Operation '${"operationName"}' can be invoked with multiple content-type. It is difficult to form a correct method signature for convenience API, and hence the convenience API is not generated.`,
@@ -92,30 +114,35 @@ export const $lib = createTypeSpecLibrary({
       },
     },
     "header-parameter-format-not-supported": {
+      ...doc("header-parameter-format-not-supported"),
       severity: "warning",
       messages: {
         default: paramMessage`Header parameter format '${"format"}' is not supported.`,
       },
     },
     "unknown-encode": {
+      ...doc("unknown-encode"),
       severity: "warning",
       messages: {
         default: paramMessage`Encode '${"encode"}' is not supported.`,
       },
     },
     "invalid-java-namespace": {
+      ...doc("invalid-java-namespace"),
       severity: "warning",
       messages: {
         default: paramMessage`Namespace '${"namespace"}' contains reserved Java keywords, replaced it with '${"processedNamespace"}'.`,
       },
     },
     "constant-header-in-response-removed": {
+      ...doc("constant-header-in-response-removed"),
       severity: "warning",
       messages: {
         default: paramMessage`Constant header '${"headerName"}' is removed from response headers.`,
       },
     },
     "spread-json-merge-patch-payload-not-supported": {
+      ...doc("spread-json-merge-patch-payload-not-supported"),
       severity: "warning",
       messages: {
         default:
@@ -123,18 +150,21 @@ export const $lib = createTypeSpecLibrary({
       },
     },
     "type-not-supported-on-text-plain": {
+      ...doc("type-not-supported-on-text-plain"),
       severity: "warning",
       messages: {
         default: paramMessage`Complex SDK type is not supported for "text/plain" content-type. Emitter would use string type on '${"operationName"}' ${"payloadKind"}.`,
       },
     },
     "client-required-false": {
+      ...doc("client-required-false"),
       severity: "error",
       messages: {
         default: "Client option 'clientRequired' can only be set to 'true'.",
       },
     },
     "response-headers-as-model-with-body": {
+      ...doc("response-headers-as-model-with-body"),
       severity: "error",
       messages: {
         default: paramMessage`Client option 'responseHeadersAsModel' cannot be used on operation '${"operationName"}', because it has a response body. It is only applicable to operations that have response headers but no response body.`,
diff --git a/packages/http-client-java/emitter/src/options.ts b/packages/http-client-java/emitter/src/options.ts
index a825f378502..f9bc8dedc3b 100644
--- a/packages/http-client-java/emitter/src/options.ts
+++ b/packages/http-client-java/emitter/src/options.ts
@@ -5,6 +5,8 @@ import type { JSONSchemaType } from "@typespec/compiler";
 // If add/remove "export" here, please also check typespec-java in autorest.java repository.
 
 export const LIB_NAME = "@typespec/http-client-java";
+export const DIAGNOSTIC_DOCS_BASE_URL =
+  "https://typespec.io/docs/emitters/clients/http-client-java/reference/diagnostics";
 
 export interface DevOptions {
   "generate-code-model"?: boolean;
diff --git a/packages/http-client-java/emitter/test/lib.test.ts b/packages/http-client-java/emitter/test/lib.test.ts
new file mode 100644
index 00000000000..8cd158f27a8
--- /dev/null
+++ b/packages/http-client-java/emitter/test/lib.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { $lib } from "../src/lib.js";
+import { DIAGNOSTIC_DOCS_BASE_URL } from "../src/options.js";
+
+describe("diagnostic documentation", () => {
+  it("links non-generic diagnostics to their documentation", () => {
+    const genericDiagnostics = new Set(["unknown-error", "generator-error", "generator-warning"]);
+
+    for (const [code, diagnostic] of Object.entries($lib.diagnostics)) {
+      const definition = diagnostic as {
+        docs?: { kind: string; path: string };
+        url?: string;
+      };
+
+      if (genericDiagnostics.has(code)) {
+        expect(definition.docs).toBeUndefined();
+        expect(definition.url).toBeUndefined();
+      } else {
+        expect(definition.docs).toEqual({
+          kind: "file-ref",
+          path: `emitter/src/diagnostics/${code}.md`,
+        });
+        expect(definition.url).toBe(`${DIAGNOSTIC_DOCS_BASE_URL}/${code}`);
+      }
+    }
+  });
+});