Setup troubleshooting checklist

"Mock Mode" showing when you expected real mode:

• You haven't configured Zendesk credentials yet. Click "Configure Zendesk" in the connection panel and enter your OAuth Client ID and Secret.

"Cannot reach backend" error:

• Confirm the backend is running: cd backend && python -m app.main
• Confirm it's on port 8000: visit http://localhost:8000/docs in your browser

OAuth redirect fails after approving in Zendesk:

• Confirm the Redirect URL in your Zendesk OAuth Client matches exactly: http://localhost:8000/api/zendesk/oauth/callback
• Check for trailing slashes — they must match

"Connection failed" after entering subdomain:

• Confirm subdomain spelling. Use only the subdomain part (e.g., "acme"), not "acme.zendesk.com"
• Confirm your Zendesk instance has API access enabled

Backend starts but shows errors:

• Confirm OPENAI_API_KEY is set in your .env file
• Confirm Python 3.11+ is installed: python --version