FAQ — self-serve fixes

What these issues have in common: the fix is not in the code — it's a setting on your side or the configuration of an external account (Google, Microsoft, Shopify…). Most take a few minutes to resolve yourself. For general symptoms, see Troubleshooting.

OneDrive / OneNote / SharePoint won't connect · "AADSTS50020" · personal account

Why: Since June 2024 Microsoft requires an Entra (Azure AD) directory to register an app; personal Microsoft accounts (MSA/OneDrive) reject a single-tenant app.

• Go to portal.azure.com → create an Entra (Azure AD) directory.
• App registrations → New registration; choose account type "Any organizational directory + personal Microsoft accounts" (multitenant + personal).
• Create a Client ID and a Client secret.
• In SemAgent's Connect with your own app panel, enter the Client ID/Secret and set Directory ID = common. (A specific directory id forces single-tenant → personal accounts are rejected.)
• Add the Redirect URI shown in the panel to your app exactly.

"redirect_uri_mismatch" when connecting

Why: The redirect URI registered in your OAuth app doesn't exactly match SemAgent's.

Fix: Copy the read-only Redirect URI from the SemAgent connect panel and paste it exactly into your app's "authorized redirect URIs" — even the smallest difference (trailing /, http/https) breaks it.

Google Drive connected but 0 documents / selected files not indexed

Why: The "only selected files (drive.file)" mode needs Google Picker API enabled in the project that calls the Picker; without it, selected files return 404.

Fix: Delete the broken connector and reconnect using "All Drive (drive.readonly)" mode (the default — most reliable, no Picker). Only use drive.file if you've enabled the Picker API in your own Google Cloud project.

Google shows an "app not verified" warning

Why: Your own OAuth app is in "Testing" mode.

Fix: This is expected and fine — no central Google verification / CASA is needed. Under Google Auth Platform → Audience → Test users, add your Google account. The app can stay in Testing.

Notion connected but no content is indexed

Why: The integration doesn't have access to the pages.

Fix: In Notion, open the page/database → "..." → Connections → add your integration. Sharing the page with the integration is required; otherwise it sees nothing.

Zendesk won't connect

Why: A password is being used; Zendesk requires an API token.

Fix: In Zendesk Admin → Apps and integrations → APIs → Zendesk API → enable Token access, then connect with email + API token. Pick the content type: Help Center articles / tickets / both.

Database (PostgreSQL/MySQL/SQL Server) won't connect / times out

Why: Your database firewall blocks SemAgent's server IP.

Fix: Allow inbound connections from SemAgent's egress IP 173.212.244.210 (firewall / pg_hba.conf / cloud "authorized networks") + open the port (5432/3306/1433) + create a read-only user for safety.

Shopify: my access token (shpat_…) no longer works

Why: Shopify removed static custom-app admin token generation.

Fix: Use the new Client Credentials connection (Client ID + Secret from your custom app) — reconnect in the E-commerce tab.

WooCommerce: where do I get the API keys?

Fix: WooCommerce → Settings → Advanced → REST API (NOT WordPress Settings) → Add key → permission: Read → paste the Consumer Key + Consumer Secret into SemAgent. Shortcut: /wp-admin/admin.php?page=wc-settings&tab=advanced&section=keys.

Agent can't send email / "smtp not configured"

Why: No SMTP/Gmail is connected, or an account password is being used.

Fix: Connect Email (SMTP) or Gmail (IMAP+SMTP); for Gmail use an App Password (2-Step Verification must be on), not your normal password.

Widget shows old answers · source line disappears

Why: The browser cached the old widget.

Fix: Hard-refresh (Ctrl/Cmd + Shift + R). Cloudflare doesn't cache the widget HTML; a hard refresh loads the latest version.

Crawl returns nothing / the site blocks it (403)

Why: The target site blocks bots (e.g. Cloudflare).

Fix: Enable the JS-render / stealth crawl option for that source (handles Cloudflare-protected pages). If only a few pages came in, also check the page-limit / URL-filter item in Troubleshooting.