Troubleshooting

Login and Authentication Issues

Cannot Log In

If you are unable to sign in to your account at app.openanalyst.com, work through the following steps:

1. Confirm you are using the correct email address. OpenAnalyst accounts are tied to a specific email — check if you might have used a different address when signing up.
2. Use the Forgot Password link on the login page to request a password reset email. The reset link is valid for one hour.
3. If you signed up via Google or GitHub OAuth, make sure you are clicking the matching social login button rather than the email/password form.
4. Check that your browser has cookies and JavaScript enabled. OpenAnalyst requires both to function.
5. Try logging in from an incognito/private window to rule out browser extension interference.
6. If your organization uses SSO and you are receiving an error, check with your IT administrator that your account is provisioned in the OpenAnalyst group within your identity provider.

Two-Factor Authentication Issues

If your 2FA code is being rejected, verify that your device's clock is synchronized (TOTP codes are time-sensitive and fail if your clock is off by more than 30 seconds). If you have lost access to your authenticator app, use one of the backup codes that were presented when you first enabled 2FA. If you have exhausted your backup codes, contact support to initiate an identity-verified account recovery process.

Data Sync and Connection Problems

Connection Test Fails

When a data source connection test fails, the error message will indicate the category of failure:

Data Not Refreshing

If dashboards are showing stale data:

• Check the data source's refresh interval under Connections > [your connection] > Settings > Refresh Schedule. The default is on-demand (no automatic refresh); set a schedule if you need periodic updates.
• Click the Refresh button on the dashboard to force an immediate query against the live data source.
• If the connection status shows "Degraded" or "Error", the data source may be temporarily unreachable. Check the connection's health indicator and view recent error logs from the connection settings page.

Slow Dashboards

Dashboard load times depend on query complexity, data volume, and the performance of your underlying data source. If dashboards are loading slowly, consider these optimizations:

• Add indexes to your database: OpenAnalyst generates standard SQL queries. If the columns used in your dashboard filters and GROUP BY clauses are unindexed, query performance will be poor regardless of OpenAnalyst settings.
• Enable query result caching: Under Connections > [your connection] > Settings > Cache, enable result caching with an appropriate TTL. Cached queries return in milliseconds instead of seconds.
• Reduce dashboard widget count: Each widget executes an independent query on load. Dashboards with 20+ widgets may load slowly. Consider splitting into multiple focused dashboards.
• Use materialized views or pre-aggregated tables: For complex analytical queries, create materialized views in your database and point the OpenAnalyst widgets at those instead of raw tables.

AI Agent Errors

AI agents are long-running processes that can fail for several reasons:

• AGENT_TIMEOUT: The agent exceeded its allowed execution time. Increase the timeout in the agent settings, or break the analysis into smaller steps.
• CONTEXT_LIMIT_EXCEEDED: The query or analysis exceeded the selected model's context window. Switch to a model with a larger context window (Claude 3.5 Sonnet or o1 support 200k tokens) or reduce the data being processed.
• QUERY_PARSE_ERROR: The AI was unable to generate a valid query from the prompt. This often happens with ambiguous column names or complex business logic. Try rephrasing the prompt with more specific column and table names.
• DATA_SOURCE_UNAVAILABLE: The agent attempted to query a data source that was unreachable at execution time. Check the connection health and retry.

Error Code Reference

Debug Mode

Debug mode provides additional diagnostic information in the interface. To enable it, open the browser console and run:

localStorage.setItem('oa_debug', 'true');
// Then refresh the page

With debug mode enabled, query panels will show the generated SQL, execution time breakdown, cache hit/miss status, and the full AI model request/response. To disable:

localStorage.removeItem('oa_debug');

Clearing Cache

If you are experiencing unexpected behavior that cannot be explained by data or configuration issues, clearing the browser cache for app.openanalyst.com can resolve stale state problems:

1. Open browser developer tools (F12 or Cmd+Option+I on Mac).
2. Right-click the browser's reload button and select Empty Cache and Hard Reload (Chrome) or equivalent in your browser.
3. Alternatively, navigate to your browser's privacy settings and clear site data specifically for app.openanalyst.com, preserving data for other sites.

Contacting Support

If the above steps do not resolve your issue, reach out to the support team:

• In-app support: Click the ? icon in the bottom-left corner of the app to open a support chat where you can describe your issue. The chat widget automatically attaches session diagnostics to your request.
• Email: Send a detailed description of the issue, including the error code (if applicable), steps to reproduce, and your workspace ID to support@openanalyst.com.
• Status page: Before contacting support for widespread issues, check status.openanalyst.com to see if there is an ongoing incident.