diff --git a/docs/assets/images/connector_visibility_warning.png b/docs/assets/images/connector_visibility_warning.png
new file mode 100644
index 00000000000..c0d3b0d25a4
Binary files /dev/null and b/docs/assets/images/connector_visibility_warning.png differ
diff --git a/docs/content/connectors/upstream/add_edit.md b/docs/content/connectors/upstream/add_edit.md
index 89efdb41a00..8013f0d084f 100644
--- a/docs/content/connectors/upstream/add_edit.md
+++ b/docs/content/connectors/upstream/add_edit.md
@@ -34,6 +34,10 @@ You can also edit an existing Connector under the **Configured Connectors** head
 
 ![image](images/add_edit_connectors_3.png)
 
+## Checking that the connector can see your data
+
+When you submit, DefectDojo asks the tool what those credentials can actually see, and tells you the answer. If the account you connected has not been granted access to any projects, hosts, or repositories, or otherwise reports no data for your credentials, DefectDojo saves the connector and shows a No Data Visible warning. A new account that is actually empty is a valid setup, and the connector will start importing as soon as data appears. If data is present but fails to be recognized, check your tool's account permissions.
+
 ## Next Steps
 
 * Now that you've added a connector, you can confirm everything is set up correctly by running a [Discover](../manage_operations/#discover-operations) operation.
diff --git a/docs/content/connectors/upstream/manage_operations.md b/docs/content/connectors/upstream/manage_operations.md
index 39554c3e232..afb10794f30 100644
--- a/docs/content/connectors/upstream/manage_operations.md
+++ b/docs/content/connectors/upstream/manage_operations.md
@@ -31,6 +31,30 @@ Each entry on the Operations Page's table is a record of an operation event, wit
 * **Trigger** describes how the event was triggered \- was it a **Scheduled** operation which ran automatically, or a **Manual** operation which was triggered by a DefectDojo user?
 * The **Start \& End Time** of each operation is recorded here, along with the **Duration**.
 
+## When a Connector runs but imports nothing
+
+An operation that succeeds is not the same as an operation that found something. If the account
+you connected cannot see any data in the tool, Discover completes normally and finds nothing to
+create, so the Connector reports success while importing no Findings.
+
+The **Upstream Connectors** page flags this on the Connector's tile:
+
+![image](images/connector_visibility_warning.png)
+
+* **Connected, but nothing is visible** means the last operation succeeded and the tool reported
+  no data at all for these credentials. This almost always means the account is missing a grant
+  in the tool rather than in DefectDojo. Hover the warning to see what to grant for that
+  specific tool.
+* **All *n* records are missing from the tool** means the Connector previously saw data and no
+  longer does. Records that disappear from the tool are kept and marked **Missing** rather than
+  deleted, so your mappings survive. Common causes are a revoked permission, a rotated
+  credential with a narrower scope, or projects deleted in the tool.
+
+Both warnings clear on their own. Once the tool reports the data again, the next Discover
+restores the records to **Good**, your existing mappings are reused, and Sync resumes importing.
+You do not need to recreate the Connector. To check a fix immediately rather than waiting for the
+next scheduled run, use [Run Discover Manually](#run-discover-manually).
+
 ## Discover Operations
 
 The first step a DefectDojo Connector needs to take is to **Discover** your tool's environment to see how you're organizing your scan data.