From ec3e42e2e5d7ac2c4b4431fd6d4746f7f96ac8fd Mon Sep 17 00:00:00 2001
From: Kevin Adams <kevin.adams@ksatechnologies.com>
Date: Fri, 26 Jun 2026 22:18:45 -0400
Subject: [PATCH] docs: add SCALE 25.04 portal PUT port field callout (#280)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SCALE 25.04 tightened the iSCSI portal PUT schema — sending port in the
listen array now returns "Extra inputs are not permitted". Added §6.9 in
getting-started.md with the correct curl example, and a matching row in
the help panel troubleshooting table.

Closes #280

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/getting-started.md      | 23 +++++++++++++++++++++++
 ui/truenas-storage-help.html |  6 ++++++
 2 files changed, 29 insertions(+)

diff --git a/docs/getting-started.md b/docs/getting-started.md
index cc5319c..7edaa53 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -301,6 +301,29 @@ apt update --allow-releaseinfo-change
 
 After that, `apt update` works normally and this prompt will not appear again for any future v3.x release. Both `v3` (Suite) and `error` (Codename) work in `sources.list` and point to the same packages.
 
+### 6.9 `PUT /api/v2.0/iscsi/portal/id/<n>` Returns "Extra inputs are not permitted" on SCALE 25.04+
+
+TrueNAS SCALE 25.04 tightened the portal PUT schema. The `port` field is no longer accepted in PUT requests — GET still returns it, but sending it back causes a validation error:
+
+```json
+{"iscsi_portal_update.listen.0.port": [{"message": "Extra inputs are not permitted", "errno": 22}]}
+```
+
+This only affects admins who manually call the TrueNAS REST API (e.g., via curl or scripts). The plugin does not create or modify portals.
+
+**Fix:** Omit `port` from the `listen` array in PUT requests:
+
+```bash
+# Correct — SCALE 25.04+
+curl -sk -X PUT -H "Authorization: Bearer <key>" \
+  -H "Content-Type: application/json" \
+  -d '{"listen": [{"ip": "0.0.0.0"}]}' \
+  https://<truenas>/api/v2.0/iscsi/portal/id/1
+
+# Wrong — causes error on SCALE 25.04+
+# -d '{"listen": [{"ip": "0.0.0.0", "port": 3260}]}'
+```
+
 ---
 
 ## 7. Uninstalling
diff --git a/ui/truenas-storage-help.html b/ui/truenas-storage-help.html
index 5ed37c9..b1cad6a 100644
--- a/ui/truenas-storage-help.html
+++ b/ui/truenas-storage-help.html
@@ -209,6 +209,12 @@ the per-VM target is automatically removed.</p>
     <td>SCALE 25.04+ may revoke keys on upgrade. Generate a new API key and update the storage
         config in Proxmox.</td>
   </tr>
+  <tr>
+    <td>Portal PUT returns "Extra inputs are not permitted" (SCALE 25.04+)</td>
+    <td>Omit the <code>port</code> field from <code>listen</code> in
+        <code>PUT /api/v2.0/iscsi/portal/id/&lt;n&gt;</code>. SCALE 25.04 no longer accepts
+        it. See §6.9 in getting-started.md.</td>
+  </tr>
 </table>
 
 <h2>Checking Logs</h2>