Troubleshooting Guide
Cross-guide index of all known issues -- each entry links directly to the embedded resolution in the relevant guide. Includes a Diagnostic Quick Reference at the bottom.
How to Use This Page
Each issue below is documented in full inside the guide where it is most contextually relevant. Click the -> Go to resolution link to jump to the step-by-step fix. The Diagnostic Quick Reference at the bottom of this page is useful for initial triage when you don't yet know which category an error falls into.
ℹ️
Can't find your issue?
Enable Debug Mode (Admin Panel -> top nav bar -> Debug toggle) for verbose logs, then email
support@flowsquad.ai with your FlowSquad version, the exact error message, and the last 50 lines of your log file.
Installation Issues
Database Connection Problems
Setup Wizard Issues
Authentication Failures
| Symptom | Likely Cause | Resolution |
|---|
| LDAP: correct password still returns "Invalid credentials" |
Wrong Bind DN format, expired service account password, or LDAPS cert not trusted |
-> Setup Guide -- LDAP Troubleshooting |
| SAML / OAuth2: clicking “Login with SAML” or “Login with Keycloak” gives a 404 on the IdP URL |
The reverse proxy (nginx or IIS ARR) is rewriting the Location header of FlowSquad’s 302 redirect, replacing the IdP hostname with the FlowSquad hostname. The browser follows the rewritten redirect back to FlowSquad, which has no /realms/... route. |
nginx: add proxy_redirect off; inside the location / block — see Reference Guide — nginx.
IIS ARR: (1) in IIS Manager → server node → Application Request Routing Cache → Server Proxy Settings → uncheck “Reverse rewrite host in response headers” → Apply; (2) add the FlowSquad-PreserveIdPLocation outbound rule to web.config — see Reference Guide — IIS.
|
| SAML: "Invalid SAML response" or "Signature validation failed" |
SP Entity ID mismatch, SP certificate not imported in IdP, or wrong attribute mapping |
-> Setup Guide — SAML Troubleshooting • Reference Guide — Keycloak SAML |
SAML: [Errno 2] No such file or directory: …onelogin\saml2\schemas\saml-schema-protocol-2.0.xsd |
Running a build older than v1.1 where the onelogin package XML schema files were not bundled into the installer. The frozen executable cannot find the schema files it needs to validate the SAML response. |
Upgrade to the latest FlowSquad build. The fix is in all three installer specs (collect_all('onelogin')) and the custom_base_path passed to OneLogin_Saml2_Auth. |
OAuth2: SSLError: certificate verify failed: self-signed certificate |
The Identity Provider (Keycloak, Okta, etc.) is using a self-signed TLS certificate. FlowSquad verifies SSL by default when calling the token and userinfo endpoints. |
In Setup Wizard → Step 4 → OAuth2, uncheck “Verify SSL certificate when connecting to Identity Provider” and save. Only do this in non-production environments; the correct long-term fix is to install a CA-signed certificate on the IdP. |
| OAuth2: "Invalid client ID" or "Unauthorized client" |
Wrong Client ID/Secret, redirect URI mismatch, or Azure admin consent not granted |
-> Setup Guide -- OAuth2 Troubleshooting |
| SAML: Keycloak redirect loop |
SP Entity ID / ACS URL port mismatch between Keycloak and FlowSquad |
-> Reference Guide — Keycloak SAML Troubleshooting |
LLM API Errors
SSL / TLS Certificate Issues
Integration Failures
Docker-Specific Issues
License Issues
Tab & UI Behavior
| Symptom | Likely Cause | Resolution |
|---|
| Generation returns empty results or spinner never stops |
No codebase loaded, no session context, or LLM rate-limited |
-> User Guide -- Troubleshooting |
| Quality Score tab returns error immediately |
No codebase loaded in Analyze tab |
-> User Guide -- Analyze Tab |
| AskProduct: "no knowledge sources found" |
No codebase or documents loaded for this product |
-> User Guide -- Analyze Tab |
| Session artifacts lost after page refresh |
Session data is in-memory only; page refresh clears unsaved session |
-> User Guide -- Session Data Lost |
| Confluence URL blank in Analyze tab even after configuring |
Confluence settings were tested before being saved |
-> Integration Guide -- Confluence |
| Design tab "Load from Database" does not populate session |
Browser cached old scripts after an upgrade |
Hard-reload: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac) |
Session shows { original_text, refined_text } as raw JSON |
Artifact saved in old format from a previous version |
Re-open Refine tab -> load from DB -> Save to Session again |
| Product Admin cannot see the Analyze tab |
Admin assignment registered by old version; needs re-save |
Admin Panel -> Products -> Edit -> re-save the admin list |
Diagnostic Quick Reference
Log File Locations
| Deployment Type | Log Location / Command |
|---|
| Windows Portable / Installer | %LOCALAPPDATA%\FlowSquad\logs\flowsquad.log |
| Windows Service | C:\Program Files\FlowSquad\logs\flowsquad.log |
| Linux (systemd) | sudo journalctl -u flowsquad -f |
| Linux (Nginx access) | /var/log/nginx/flowsquad-access.log |
| Linux (Nginx errors) | /var/log/nginx/flowsquad-error.log |
| Docker | docker compose logs -f flowsquad |
Enabling Debug Mode
Global Admins see a Debug toggle in the top navigation bar. Click it to enable verbose logging -- the indicator turns green when active. Debug logs include detailed API call timing, LLM request/response summaries, and database query information.
⚠️
Production Warning -- Debug mode exposes sensitive request details in logs. Enable only during active troubleshooting and disable immediately afterwards.
Quick Health Checks
| Check | Where |
|---|
| LLM provider connectivity | Admin Panel -> LLM Configuration -> Test button next to each provider |
| Database connection status | Admin Panel -> Database Settings -> Connection Status |
| License validity and expiry | Admin Panel -> License Management |
| Active user sessions | Admin Panel -> Analytics -> Active Users |
| Audit log for suspicious activity | Admin Panel -> Audit Logs -> filter by severity: Warning / Error |
Common Error Strings -> Root Cause Map
| Error String (in logs or UI) | Root Cause | Where to Fix |
|---|
License validation failed: Machine ID does not match | Server migrated or wrong cluster ID | Admin Guide |
could not connect to server: Connection refused | PostgreSQL not running or wrong port | Setup Guide |
LDAP bind failed | Wrong Bind DN, expired service account, or LDAPS cert untrusted | Setup Guide |
Invalid SAML response / Signature validation failed | SP Entity ID mismatch or SP cert not imported in IdP | Setup Guide |
Rate limit exceeded (429) | OpenAI / GitHub Models free tier or Tier 1 limits | Admin Guide -- LLM Config |
Authentication error: Invalid API key (401 -- Anthropic) | API key expired or wrong workspace | Admin Guide -- LLM Config |
PermissionError: [Errno 13] Permission denied (Docker) | Volume owned by root; container user (1000) cannot write | Install Guide |
Jira API call failed: 401 Unauthorized | Jira API token expired or wrong Jira type (Cloud vs. Server) | User Guide |
Contacting Support
Email support@flowsquad.ai and include:
- FlowSquad version (Admin Panel -> License Management)
- Exact error message text (copy from the UI or log)
- Log file excerpt -- last 50 lines from the log file location above
- Deployment type: Windows / Linux / Docker / Kubernetes
- Steps to reproduce the issue
Response times: 24 hours (Enterprise), 7 days (Evaluation).