diff --git a/docs/content/exporters/formats.md b/docs/content/exporters/formats.md
index 6360c66cd..24ee9edf8 100644
--- a/docs/content/exporters/formats.md
+++ b/docs/content/exporters/formats.md
@@ -66,6 +66,12 @@ You can exclude the shaded protobuf classes including the
 `prometheus-metrics-exposition-formats-no-protobuf` module and excluding the
 `prometheus-metrics-exposition-formats` module in your build file.
 
+If you are using the PushGateway in a shaded jar with `minimizeJar=true`, do not use this setup.
+The PushGateway loads the protobuf writer implementation via reflection, so the full
+`prometheus-metrics-exposition-formats` artifact must stay on the classpath and the relevant
+packages must be preserved during shading. See the [PushGateway docs]({{< relref
+"./pushgateway.md" >}}) for the recommended Maven Shade configuration.
+
 For example, in Maven:
 
 ```xml
diff --git a/docs/content/exporters/pushgateway.md b/docs/content/exporters/pushgateway.md
index d3713769d..755525dd9 100644
--- a/docs/content/exporters/pushgateway.md
+++ b/docs/content/exporters/pushgateway.md
@@ -115,7 +115,8 @@ PushGateway pushGateway = PushGateway.builder()
 However, this requires that the JVM can validate the server certificate.
 
 If you want to skip certificate verification, you need to provide your own
-[HttpConnectionFactory](/client_java/api/io/prometheus/metrics/exporter/pushgateway/HttpConnectionFactory.html).
+`HttpConnectionFactory`. See the
+[API docs](/client_java/api/io/prometheus/metrics/exporter/pushgateway/HttpConnectionFactory.html).
 The `PushGatewayTestApp` in `integration-tests/it-pushgateway` has a complete example of this.
 
 ## Configuration Properties
@@ -123,3 +124,34 @@ The `PushGatewayTestApp` in `integration-tests/it-pushgateway` has a complete ex
 The [PushGateway](/client_java/api/io/prometheus/metrics/exporter/pushgateway/PushGateway.html)
 supports a couple of properties that can be configured at runtime.
 See [config]({{< relref "../config/config.md" >}}).
+
+## Troubleshooting shaded jars
+
+If you build a shaded jar with the Maven Shade Plugin and `minimizeJar=true`, the PushGateway may
+fail at runtime with an error like this:
+
+```text
+java.lang.RuntimeException: class
+io.prometheus.metrics.expositionformats.PrometheusProtobufWriter is not available
+```
+
+This happens because the PushGateway loads the protobuf writer implementation via reflection. The
+Maven Shade Plugin does not detect that reflective usage during minimization, so it may strip the
+required classes from the final jar.
+
+To avoid this, keep the `prometheus-metrics-exposition-formats` artifact on the classpath and
+preserve the protobuf-related packages in your shade configuration:
+
+```xml
+<filters>
+  <filter>
+    <artifact>io.prometheus:prometheus-metrics-exposition-formats</artifact>
+    <includes>
+      <include>io/prometheus/metrics/expositionformats/**</include>
+      <include>io/prometheus/metrics/shaded/**</include>
+    </includes>
+  </filter>
+</filters>
+```
+
+Alternatively, disable jar minimization for the shaded build.