Skip to content
flow8

Troubleshooting Guide

Troubleshooting Guide

1. MongoDB Connection Refused

Symptoms: Server fails to start. Log shows mongodb: connection refused or dial tcp: connect: connection refused.

Causes & Fixes:

  • MongoDB is not running — start it: docker-compose up -d mongo
  • Wrong MONGODB_URI format — must be: mongodb://host:port (no trailing slash)
  • MongoDB is on a different network — ensure app and mongo are on the same Docker network
  • Auth required but not in URI — use: mongodb://user:pass@host:27017/dbname?authSource=admin
  • Firewall blocking port 27017 — check ufw status or security group rules
Terminal window
# Test connectivity
mongosh "mongodb://localhost:27017" --eval "db.runCommand({ ping: 1 })"

2. Encryption Key Errors

Symptoms: invalid key length, decryption failed, or startup panic related to encryption.

Cause: ENV_KEY_SALT must be exactly 64 hex characters (32 bytes). ENC_KEY_SECRET must be exactly 256 hex characters (128 bytes).

Terminal window
# Count characters
echo -n "$ENV_KEY_SALT" | wc -c      # Must be 64
echo -n "$ENC_KEY_SECRET" | wc -c   # Must be 256


# Generate correct values
openssl rand -hex 32    # → 64 chars (for ENV_KEY_SALT)
openssl rand -hex 128   # → 256 chars (for ENC_KEY_SECRET)

Important: Changing these keys after data has been stored will make all encrypted data (KV values, OAuth tokens, credentials) unreadable. Never rotate keys without a migration plan.

3. Module Not Discovered

Symptoms: Module doesn’t appear in the UI or API after adding it. No error at startup.

Cause: The factory method name doesn’t follow the required naming convention.

Fix: The factory method must:

  • Be a method on *PluginModule (not on your module struct)
  • Be named exactly NewModule<CamelName> (case-sensitive)
  • Return a pointer to your module struct
// ✅ Correct
func (p *PluginModule) NewModuleMyTool() *ModuleMyTool { ... }


// ❌ Wrong — receiver is wrong
func (m *ModuleMyTool) NewModuleMyTool() *ModuleMyTool { ... }


// ❌ Wrong — method name doesn't start with NewModule
func (p *PluginModule) CreateMyTool() *ModuleMyTool { ... }

Also verify the file is in pkg/plugins/layers/v2/ and the package declaration is package layers.

Set APPS_FORCEUPDATE=true and restart to force re-registration.

4. Channel Port Conflicts

Symptoms: Channel fails to start. Error: address already in use or bind: permission denied.

Causes:

  • Another process is using a port in the 7701-7799 range
  • Running multiple flow8 instances with overlapping port ranges
  • Channel was not properly stopped and port is still held

Fix:

Terminal window
# Find what's using the port
lsof -i :7701


# Kill the process if it's a stale flow8 process
kill -9 <PID>

For multiple instances, configure non-overlapping ranges in each instance’s CHANNEL_PORT_RANGE (e.g., 7701-7750 and 7751-7799).

5. LibreOffice / Tesseract Not Working

Symptoms: Document conversion or OCR modules fail. Error: soffice not found or tesseract: command not found.

Checklist:

  1. Verify binaries are installed: which soffice && soffice --version
  2. Check CAPS_SOFFICE=true and CAPS_TESSERACT=true in .env
  3. Verify .config.yaml has correct path.soffice: 
    path:
      soffice: "/usr/bin/soffice"   # Linux
      # soffice: "/Applications/LibreOffice.app/Contents/MacOS/soffice"  # macOS
  4. In Docker, these are pre-installed in the image. If running from source, install system packages.
  5. LibreOffice may fail if no display is available — set DISPLAY=:0 or use a headless config.

6. CORS Errors

Symptoms: Browser requests blocked with CORS policy: No 'Access-Control-Allow-Origin' header.

Fix: Add the frontend origin to ALLOWED_ORIGINS:

ALLOWED_ORIGINS=http://localhost:3000,https://app.yourcompany.com

Also ensure FRONTEND_URL is set correctly. If using cookies for auth, allowCredentials: true (already set in config.yml) requires that ALLOWED_ORIGINS is not * — it must list explicit origins.

7. OAuth2 Redirect Failures

Symptoms: Microsoft OAuth2 login fails with redirect_uri_mismatch or AADSTS50011.

Fix: The redirect URI registered in Azure AD must exactly match the one flow8 generates:

https://your-domain.com/api/auth/oauth2/microsoft/callback

Register this exact URL in your Azure AD app’s Redirect URIs (under Authentication). Ensure API_URL is set to the correct public base URL.

8. Session Expiry Issues

Symptoms: Users are logged out unexpectedly or session cookies are not set.

Fixes:

  • Increase session TTL in config/config.yml: auth.session.lifeTime: 86400 (24 hours)
  • Set COOKIE_DOMAIN if frontend is on a subdomain: COOKIE_DOMAIN=.yourcompany.com
  • Ensure the frontend is sending cookies with requests (credentials: 'include' in fetch)
  • Check that TLS is in use — Secure cookies require HTTPS

9. High Memory Usage

Symptoms: Process memory grows over time without leveling off.

Likely causes:

  1. TTL cache not evicting — verify ClearTTLCache job is running (check logs for 1-minute interval)
  2. Retention cleanup not running — verify RetentionPolicyService cleanup job is active
  3. plays and audit collections growing unbounded — configure retention policies
  4. Large flow output data stored in memory — reduce UNIT_OUTPUT_UI_MAX_BYTES

10. Slow Flow Execution

Symptoms: Flows take much longer than expected.

Checklist:

  1. Add MongoDB indexes (see Database Setup — Recommended Indexes)
  2. Check if MongoDB is CPU/IO bound: mongostat
  3. Review module component timeouts — unreachable external services cause waits
  4. Use the WebSocket stream to identify which specific flowlet is slow
  5. Enable query profiling in MongoDB: db.setProfilingLevel(1, { slowms: 100 })

11. MCP Auth Failures

Symptoms: AI agent cannot authenticate with the MCP server on port 4445. Error: invalid token or unauthorized.

Fix:

  • Ensure MCP_JWT_SECRET is set and matches the secret used to sign the JWT
  • The JWT must include scope: "mcp" in its claims
  • Verify the MCP server is running (check logs for MCP server started on :4445)
  • Test with a manually generated JWT: {"userId": "...", "companyId": "...", "scope": "mcp"}

12. Build Failures (Private Modules)

Symptoms: go mod download or go run fails with module not found or authentication required.

Fix:

Terminal window
# Set credentials
export GOPRIVATE=git.qix.sx/gorgany/gorgany.git
export GOPROXY=https://goproxy.cn


# Configure Git to inject credentials
git config --global url."https://USERNAME:TOKEN@github.com/".insteadOf "https://github.com/"


# Clear module cache and retry
go clean -modcache
go mod download