Integrations troubleshooting

Connect failed. CONNECTOR_ENCRYPTION_KEY is not configured

Cause. server missing the environment secret (or APP_ENV is not an explicit local value)

Fix. set a unique 32-byte hex (or base64) key in Compose environment secrets for staging/production, or .dev.vars locally. Only APP_ENV=development|test|local may omit the key (documented fallback)

invalid_state or state_replay on OAuth return

Cause. OAuth state is single-use and expires in about 10 minutes, or the callback hit a different APP_URL host

Fix. restart Authorize from the Connect page and ensure APP_URL matches the registered redirect host

Microsoft Graph 403

Cause. missing admin consent for Files.ReadWrite.All and Sites.ReadWrite.All

Fix. re-consent those scopes, then authorize again

Northdocs' Microsoft app isn't available in this environment

Cause. this environment does not have the Northdocs Microsoft app configured

Fix. choose Your own Entra app, or ask your Northdocs contact

Graph delta 410 Gone

Cause. delta cursor expired

Fix. none required. Northdocs automatically performs a full resync and stores a new cursor

File too large

Cause. imports share the 100 MB interactive upload limit

Fix. split the package or upload oversized files manually

HighQ list returns HTML / parse errors

Cause. wrong instance URL or API not returning JSON

Fix. use https://host/instance form, confirm API app registration, retry with mock mode to isolate Northdocs UI

Datasite APIs unavailable

Cause. Developer APIs not enabled

Fix. contact developer@datasite.com; use mock mode meanwhile

write-back error on connector card

Cause. destination folder permissions, expired token, or network/SSRF guard

Fix. refresh auth, verify folder id, check Activity / audit for the connector.writeback event detail

ESDH connect fails with URL must be a public HTTPS endpoint

Cause. apiBaseUrl/tokenUrl is http, private, or metadata without a private link

Fix. expose the journal on public HTTPS, or use Enterprise Private connector (Private connector (on-prem ESDH / DMS)) and select that link on the Connect page

S3 private-link Endpoint rejected

Cause. Endpoint host is not on the private link allowlist

Fix. set Endpoint to your private MinIO host (or another allowlisted host on that link). SigV4 Host stays on that hostname; traffic is mesh-routed

Private connector link is not active

Cause. Link not provisioned, NetBird agent not installed, peer not connected, or the link was disabled

Fix. use Set up private connector (or ask support); finish NetBird install from Install instructions; run Health check to activate. Delete a requested, pending, or failed link if you need to start over

Health check says peer not connected yet

Cause. The NetBird setup key was issued, but no healthy customer peer has joined the mesh (or the agent stopped)

Fix. install NetBird from https://docs.netbird.io/how-to/installation , run the Install instructions command (netbird up --management-url … --setup-key …) on a host that can reach the private target, confirm the agent is connected, then retry Health check. Refresh the setup key if you rotated credentials or the old key was lost

GetOrganized 401 with NTLM-only account

Cause. the hosted connector runtime cannot speak NTLM

Fix. terminate NTLM at a reverse proxy and issue Basic/Bearer to Northdocs (works with public HTTPS or private link)