beatsad_Vault2Dify/docs/CONNECTION_TROUBLESHOOTING.md

Connection Troubleshooting

English | 中文

Use this guide when Vault2Dify fails during connection testing, knowledge-base refresh, or file sync.

Quick Check Order

Order	Check	Notes
1	API Key	Confirm it is present, complete, and has no extra spaces or line breaks.
2	Dify service URL	Enter the Dify service URL reachable from this Obsidian device. The plugin normalizes omitted http://, /v1, and /v1/datasets.
3	Browser access	Open your URL + /v1/datasets in a browser.
4	Response content	JSON usually means the URL is close; HTML usually means the URL or port is wrong.
5	Permissions	If the URL works but no knowledge bases appear, check workspace and knowledge-base permissions.
6	Network path	Check ports, firewall, Docker mapping, NAS network, Tailscale, and reverse proxy rules.
7	Plugin retest	Return to settings and click Test connection.

Error Reference

Error message	Status	Likely cause	What to do	How to confirm
Please fill in Dify API Key and Dify service URL first.	missing_config	Required connection fields are incomplete.	Fill the API key and reachable Dify service URL, then test again.	Status moves away from Pending setup and shows success or a specific failure.
API Key is invalid. Please check whether the key is correct.	auth_failed	Dify returned 401.	Copy the Dify Knowledge Base API Key again; remove extra whitespace; confirm the key belongs to this Dify instance.	The invalid-key message disappears.
API Key does not have knowledge-base access. Please check Dify permissions.	permission_denied	Dify returned 403.	Confirm the key belongs to the right workspace and has knowledge-base permissions.	Test connection can load knowledge bases.
Dify Knowledge Base API was not found. Check the Dify service URL, port, and reverse proxy forwarding.	not_found	Dify returned 404 for the API path.	Use a reachable service URL such as http://dify-host.example.test:5000, or a NAS Tailscale URL such as http://tailnet-device.example.test:5000; check reverse proxy forwarding for /v1.	Browser access to URL + /v1/datasets no longer returns 404.
Current API path is incompatible. Upgrade to the latest build and retry.	path_mismatch	Dify document API path did not match the plugin compatibility layer.	Confirm the plugin is on the latest build; retry Test connection, then sync; if it persists, enable debug logs and report Dify version plus error details.	Document sync no longer reports path incompatibility.
Dify returned too many requests. Lower concurrent uploads or retry later.	rate_limited	Dify returned 429.	Lower concurrent uploads, retry later, or sync large folders in batches.	Sync no longer reports rate limiting and failed counts decrease.
Dify service error. Check Dify containers, service logs, or reverse proxy.	server	Dify returned 5xx.	Check Dify service health, container logs, and reverse proxy upstream settings.	/v1/datasets no longer returns 5xx and plugin testing succeeds.
Request timed out. Confirm that this device can reach the Dify service URL.	timeout	The request did not complete within the plugin's internal timeout.	Confirm network reachability; check Dify load, ports, firewall, Tailscale, and reverse proxy; for large syncs, lower concurrent uploads to 2 files or sync in smaller batches.	Tests return results and sync no longer times out frequently.
Network connection failed. Check URL, port, firewall, Docker mapping, or reverse proxy.	network	The Obsidian device cannot connect to the target address.	Check IP, domain, port, Docker mapping, firewall, routing, Tailscale, and reverse proxy service.	Browser can open URL + /v1/datasets and plugin testing no longer shows network failure.
The current address did not return the Dify Knowledge Base API. Check whether the URL and port point to Dify.	unexpected_response	The request reached a web page, login page, NAS admin page, Dify frontend page, or another non-Dify API response.	Use the Dify service root URL; do not use a NAS admin URL; confirm the port and reverse proxy return Dify API JSON.	The unexpected-response message disappears and testing shows knowledge bases or a permission error.
Connection failed. Check Dify configuration and retry.	unknown	The plugin could not classify the failure.	Follow the quick checks for key, URL, port, and proxy; temporarily enable debug logs; retest and inspect the Obsidian developer console.	A more specific error appears, or testing succeeds.

URL Rules

Type	Example	Recommended	Notes
Dify service URL	http://dify-host.example.test:5000	Yes	Common for LAN, NAS, and Docker deployments.
NAS + Tailscale	http://tailnet-device.example.test:5000	Yes	Use a tailnet device hostname or documented example host plus the mapped Dify port.
Dify HTTPS domain	https://dify.example.com	Yes	Suitable for public reverse proxy or Dify Cloud.
Pasted /v1 endpoint	http://dify-host.example.test:5000/v1	Accepted	The plugin normalizes known Dify suffixes, but the service URL is clearer.
Pasted /v1/datasets endpoint	http://dify-host.example.test:5000/v1/datasets	Accepted	The plugin normalizes this known endpoint to the service URL.
NAS admin page	https://nas-admin.example.test/admin	No	Usually returns HTML, not the Dify Knowledge Base API.
Docker-internal address	http://api:5001	No	The Obsidian device usually cannot access container-internal addresses.
Remote localhost	http://localhost:5000	Usually no	Use only when Dify and Obsidian run on the same computer.

Browser Verification

Browser result	Meaning	Next step
JSON response	The URL is likely correct.	If the plugin still fails, check API key and knowledge-base permissions.
HTML page	The address or port points to a web service.	Check whether it is a NAS admin page, Dify frontend, or wrong proxy target.
404	The API path does not exist.	Check the service URL, port, and reverse proxy forwarding for /v1.
401	The URL may be routed to Dify correctly.	Confirm the plugin API key is correct.
403	The service is reachable but permissions are insufficient.	Check key permissions and workspace.
Cannot connect	The network path is unreachable.	Check IP, domain, port, firewall, Docker mapping, Tailscale, and proxy.

Sync Failure Checks

Symptom	Check first	Action
Whole sync fails	Click Test connection.	If testing fails, follow the error table above.
Some files fail	Check Recent failed files.	Use the failure reason to inspect permissions, network, timeout, or rate limiting.
Many files fail	Concurrency, rate limits, service load.	Lower concurrent uploads and sync large folders in batches.
Test succeeds but sync fails	Mapping and write permissions.	Confirm the path mapping is enabled and target knowledge bases are writable.

When to Enable Debug Logs

Scenario	Recommendation
The error stays generic.	Enable debug logs and inspect lower-level response details.
Browser verification works but the plugin still fails.	Enable debug logs and compare the plugin's actual request URL.
NAS, Docker, or reverse proxy routing is complex.	Enable debug logs to confirm requests reach the Dify API.
You need to report an issue.	Include relevant logs, but never publish API keys or sensitive note content.