From 27ca5c61dde2ed665c62a923f9afda9da509bcb9 Mon Sep 17 00:00:00 2001
From: gvdongen <14088558+gvdongen@users.noreply.github.com>
Date: Mon, 6 Jul 2026 09:18:39 +0000
Subject: [PATCH] chore: sync java-api-and-pitfalls.md from docs-restate

---
 .../.aiassistant/rules/java-api-and-pitfalls.md   | 15 +++++++++++++++
 .../.aiassistant/rules/java-api-and-pitfalls.md   | 15 +++++++++++++++
 .../.aiassistant/rules/java-api-and-pitfalls.md   | 15 +++++++++++++++
 .../.aiassistant/rules/java-api-and-pitfalls.md   | 15 +++++++++++++++
 4 files changed, 60 insertions(+)

diff --git a/java/templates/java-gradle/.aiassistant/rules/java-api-and-pitfalls.md b/java/templates/java-gradle/.aiassistant/rules/java-api-and-pitfalls.md
index 3405ef1d..dda02f99 100644
--- a/java/templates/java-gradle/.aiassistant/rules/java-api-and-pitfalls.md
+++ b/java/templates/java-gradle/.aiassistant/rules/java-api-and-pitfalls.md
@@ -431,6 +431,21 @@ Note: the Java SDK uses `TerminalException`, NOT `TerminalError` (which is used
 
 Any other exception type causes automatic retries with exponential backoff. For retry policy configuration, refer to the retry guide.
 
+### TerminalException metadata
+
+You can attach a string metadata map to a `TerminalException`. The metadata is propagated to callers and accessible via `getMetadata()`. Requires Restate Server >= 1.6.
+
+```java
+throw new TerminalException("Something went wrong", Map.of("correlationId", correlationId));
+```
+
+Callers can read the metadata:
+
+```java
+Map<String, String> metadata = e.getMetadata();
+String correlationId = metadata.get("correlationId");
+```
+
 ---
 
 ## SDK Clients (External Invocations)
diff --git a/java/templates/java-maven-quarkus/.aiassistant/rules/java-api-and-pitfalls.md b/java/templates/java-maven-quarkus/.aiassistant/rules/java-api-and-pitfalls.md
index 3405ef1d..dda02f99 100644
--- a/java/templates/java-maven-quarkus/.aiassistant/rules/java-api-and-pitfalls.md
+++ b/java/templates/java-maven-quarkus/.aiassistant/rules/java-api-and-pitfalls.md
@@ -431,6 +431,21 @@ Note: the Java SDK uses `TerminalException`, NOT `TerminalError` (which is used
 
 Any other exception type causes automatic retries with exponential backoff. For retry policy configuration, refer to the retry guide.
 
+### TerminalException metadata
+
+You can attach a string metadata map to a `TerminalException`. The metadata is propagated to callers and accessible via `getMetadata()`. Requires Restate Server >= 1.6.
+
+```java
+throw new TerminalException("Something went wrong", Map.of("correlationId", correlationId));
+```
+
+Callers can read the metadata:
+
+```java
+Map<String, String> metadata = e.getMetadata();
+String correlationId = metadata.get("correlationId");
+```
+
 ---
 
 ## SDK Clients (External Invocations)
diff --git a/java/templates/java-maven-spring-boot/.aiassistant/rules/java-api-and-pitfalls.md b/java/templates/java-maven-spring-boot/.aiassistant/rules/java-api-and-pitfalls.md
index 3405ef1d..dda02f99 100644
--- a/java/templates/java-maven-spring-boot/.aiassistant/rules/java-api-and-pitfalls.md
+++ b/java/templates/java-maven-spring-boot/.aiassistant/rules/java-api-and-pitfalls.md
@@ -431,6 +431,21 @@ Note: the Java SDK uses `TerminalException`, NOT `TerminalError` (which is used
 
 Any other exception type causes automatic retries with exponential backoff. For retry policy configuration, refer to the retry guide.
 
+### TerminalException metadata
+
+You can attach a string metadata map to a `TerminalException`. The metadata is propagated to callers and accessible via `getMetadata()`. Requires Restate Server >= 1.6.
+
+```java
+throw new TerminalException("Something went wrong", Map.of("correlationId", correlationId));
+```
+
+Callers can read the metadata:
+
+```java
+Map<String, String> metadata = e.getMetadata();
+String correlationId = metadata.get("correlationId");
+```
+
 ---
 
 ## SDK Clients (External Invocations)
diff --git a/java/templates/java-maven/.aiassistant/rules/java-api-and-pitfalls.md b/java/templates/java-maven/.aiassistant/rules/java-api-and-pitfalls.md
index 3405ef1d..dda02f99 100644
--- a/java/templates/java-maven/.aiassistant/rules/java-api-and-pitfalls.md
+++ b/java/templates/java-maven/.aiassistant/rules/java-api-and-pitfalls.md
@@ -431,6 +431,21 @@ Note: the Java SDK uses `TerminalException`, NOT `TerminalError` (which is used
 
 Any other exception type causes automatic retries with exponential backoff. For retry policy configuration, refer to the retry guide.
 
+### TerminalException metadata
+
+You can attach a string metadata map to a `TerminalException`. The metadata is propagated to callers and accessible via `getMetadata()`. Requires Restate Server >= 1.6.
+
+```java
+throw new TerminalException("Something went wrong", Map.of("correlationId", correlationId));
+```
+
+Callers can read the metadata:
+
+```java
+Map<String, String> metadata = e.getMetadata();
+String correlationId = metadata.get("correlationId");
+```
+
 ---
 
 ## SDK Clients (External Invocations)