diff --git a/docs/swarm/ui.md b/docs/swarm/ui.md
index 860d38f6..d2c7be61 100644
--- a/docs/swarm/ui.md
+++ b/docs/swarm/ui.md
@@ -432,6 +432,10 @@ as optional `limits` and `inference` objects, the same shapes the two `PUT`
 routes take. The controller checks them with the `PUT` rules before it queues
 anything, so a bad value gets a refusal with its reason and creates no agent.
 
+The dialog loads the hive list and the permission list when it opens. If either
+load fails, the dialog says why in place of an empty picker, with the text
+`could not load hives` or `could not load permissions`.
+
 It stores them ahead of the job graph, before it declares the agent, so they
 are in place before the agent first runs. If the creation then fails, the
 controller puts back what it replaced. Each agent name keys its settings and