Skip to main content
This page documents commonly reported issues and their recommended solutions, organized by category.

​
Threads & Chat

Long threads can fail to load, especially if they contain large file previews or have exceeded the context window.Solution:
  • Start a new thread for your next question. Long threads are more expensive and less token-efficient.
  • If you need to reference prior work, ask Ana to summarize the key findings and carry them into the new thread.
This error means Ana’s execution environment is rebuilding and temporarily cannot accept queries, likely an issue from the model provider.Solution: Start a new thread with a fresh chat ID. If the error persists across new threads, contact support@textql.com.
This is a known rendering issue that can occur when charts are generated in certain thread states.Solution: Re-run the query in a new thread. If the issue persists, submit a bug report using the feedback button in the app.

​
Playbooks

If a playbook runs on schedule and results appear in the TextQL console but not in the designated Slack channel, the Slack integration may be misconfigured or the bot may not have channel access.Solution:
  1. Confirm the Slack integration is working by tagging @Ana in the selected channel.
  2. Make sure the playbook has the correct Slack channel configured in its delivery settings and that the playbook is NOT set as “channel context”.
  3. Verify that the Ana Slack bot has been invited to the channel.
If tagging Ana in Slack produces no response, the Slack integration may need to be re-synced. Contact support@textql.com.
Playbooks perform best when the request is tightly scoped. Layering too many business requirements (usage trends, revenue, churn, acquisition, etc.) into one playbook can cause inconsistent format or incomplete scope during each playbook runSolution:
  • Workshop with Ana in a thread to get to your desired output format, then ask Ana to build a playbook and retain necessary SQL/Python code to reproduce the desired output format.
  • Add in the playbook prompt “look at previous playbook reports and follow the same output format” once you achieve a desired format.
  • Break complex reports into multiple focused playbooks, each covering a single domain.
  • Consider building a TextQL dashboard for the underlying metrics, then running a playbook that reads from the dashboard for the narrative summary.

​
Dashboards

If an unpublished dashboard is not edited, it cannot be reverted to the previous versionSolution: Make sure to publish dashboard if you want to potentially revert back to this version while editing. Publish = Save. If you edit a publish dashboard, you will see a red revert button (top right) once changes are made to the dashboard. If you want to revert to a previous unpublished working version, contact support@textql.com with the dashboard URL. The engineering team can restore the previous working version.

​
Ontology

There are several approaches for building or managing an ontology outside the TextQL UI.Solution:
  1. AI-assisted: Make sure Ontology Editor toggle is switched on before the start of the chat (optional to switch on auto-approve). Ask Ana to explore your connector’s foreign keys and create ontology objects and links based on the schema. Provide a prompt with your table list and domain context.
  2. Import/export existing Ontology: Ontologies can be exported and imported as JSON files, enabling version control via GitHub and programmatic manipulation.
  3. API-based: Use the TextQL API with a self-issued API key to create and manage ontology objects programmatically.
For large ontology builds, using GitHub for source control between versions is recommended. See Ontology Overview.
When importing an ontology via JSON, relationships (joins) between objects may not be created automatically even if they are defined in the file.Solution: After importing, ask Ana to explore the foreign keys in your connector and create links based on matching relationships. Provide a prompt specifying which objects should be linked and on which keys.
Ontologies can be copied to a new connector or transferred to a new TextQL environment.Solution: Contact your TextQL account manager or support@textql.com to export the ontology as JSON. This can be re-imported into a new connector or a new environment.
If a playbook or a thread was done in Ontology mode only, users need to have access to the ontology to have the permission to run them. If a user has connector access but not ontology access, they will see permission errors when trying to edit the playbook or the thread.Solution: Grant the user access to the relevant ontology, even if it is empty. This can be done in the ontology settings.

​
Organization Context & Ana Behavior

Context error banner in Ana
Organization context is injected into Ana’s system prompt at the start of every thread. However, Ana may skip the context step when the prompt contains recognizable table or column names.Solution: To improve adherence:
  1. Use explicit, firm instructions in your context file:
    ALWAYS access the GitHub context repo before running any query, EVEN IF you recognize table names in the user's prompt.
  2. Avoid contradicting instructions across different context files.
  3. Keep context concise. Overly long context reduces Ana’s ability to follow specific instructions. If threads are hitting the maximum length banner, context size may be a contributing factor.
  4. Use an ontology for critical data routing rules. Ontologies provide a more structured and reliable way to guide Ana than free-text context. See Ontology Overview.
Related docs:
Using a GitHub repo for context gives you version control and allows Ana to selectively pull context instead of getting it all at once.Solution:
  1. Create a GitHub repo for your context files.
  2. Generate a Personal Access Token (PAT) with read access.
  3. Add the PAT in the Connectors > Env Vars section.
  4. Add a note in your organization context telling Ana to reference the repo.
For admin-only write access, create two PATs: one read-only for members and one read-write for admins, assigned to different roles.See GitHub Integration for Context and What is Context.

​
Connectors & Data Sources

TextQL enforces the following guardrails by default:
GuardrailDefault Value
SQL execution timeout3 minutes per query
DDL schema introspection timeout30 seconds
Request lifecycle timeout5 minutes
Row cap per query2 million rows
Write protectionSELECT only (all DDL/DML blocked)
Query throttlingNone (subject to your database’s limits)
These limits are part of the application’s internal configuration and are not customer-configurable in cloud deployments.Solution: For VPC deployments, contact your TextQL account manager to customize the row cap and other limits. For connector setup, see The Connectors Page. For security details, see Security Whitepaper.
Programmatic connector management and credential rotation can be handled via the TextQL API.Solution: See the API Reference for available endpoints. For credential rotation integrated with AWS Secrets Manager or another vault, contact support@textql.com to discuss options for your deployment.
If Ana returns results from schemas or tables beyond what the connector should access, the connector’s database user may have broader permissions than intended.Solution:
  • Restrict at the database level: Review the role/user assigned to the connector and revoke access to any schemas or tables Ana should not see.
  • Use Organization Context: Add instructions in the Context Library specifying which tables Ana should or shouldn’t use for certain questions. Note that LLM behavior is non-deterministic — context instructions guide but do not strictly enforce Ana’s behavior.
  • Use an ontology for deterministic access control: Only fields explicitly defined as dimensions or measures are exposed to Ana. See Ontology Overview.
There are two approaches for connecting dbt documentation or a semantic layer to TextQL.Solution:
  1. Persist dbt docs to your data warehouse (e.g., BigQuery) and let Ana query them via an existing connector. This is the simplest path.
  2. Use the dbt Discovery API via a service token. Add the token in the “Env Vars” section of the Connectors page, and add a note in your organization context telling Ana when to reference it.
For dbt Cloud semantic layer API integration, this is under active development. Contact your account manager for the latest status.
This typically means the Personal Access Token (PAT) or credential used by the connector has expired. Many data sources (e.g., Databricks, Snowflake, BigQuery service accounts) issue tokens or keys with a configurable expiry.Solution: Regenerate a new token or credential in your data source, then go to the Connectors page, update the credential field with the new value, and save. The connector should resume working immediately.
If the connector test succeeds but Ana fails to return data, the connector metadata may be stale or corrupted. You may also see an error like:
Execution error: failed to execute sql: uploading table: sql upload table failed after 1 attempts: engine mode not supported for PostgresConnector on Postgres
Solution: Delete and recreate the connector. This resolves cases where the connector metadata is stale or corrupted.
TextQL supports Oracle Base DB and Oracle ADW via native connectors with ontology support. Oracle Fusion is supported via API. Oracle OAC has partial API support.Solution: For the latest availability and timeline on Oracle integrations, contact your TextQL account manager.
A pre-built Jira connector is not yet available.Solution: Connect Jira via API key using the Env Vars section on the Connectors page. A pre-built connector is on the roadmap.

​
Roles & Permissions

Connector access is managed on the Connectors page, not the Roles page.
Connectors page showing the '...' menu with Manage Access option
Solution:
  1. Set the connector to Restricted Access by clicking … > Manage Access on the connector.
Manage connector access modal showing restricted access, role selection, and permission level
  1. Add the specific role under Select roles to share with and set the permission level to Viewer.
Users with that role will only see connectors explicitly shared with them. Note: users can still start chats without selecting a connector.
There are two approaches depending on your setup.Solution:
  • Ontology mode: Only fields marked as dimensions or measures are exposed to Ana. Remove or don’t add sensitive fields (e.g., password, SSN) as attributes. Alternatively, define the ontology object with a custom SELECT query that excludes sensitive columns.
  • Text-to-SQL mode: Restrict the connector’s database user permissions at the database level, or use database views that exclude sensitive columns.
For deterministic security, ontology mode is recommended over text-to-SQL. See Ontology Overview.
The public and private permission model controls which conversations users can view.Solution: Permissions work as follows:
  • Read/Write Public: The user can view or create conversations that have been intentionally set to public. All chats are private by default.
  • Read/Write Private: The user can view all conversations, including other users’ private chats. This should be reserved for admin or security roles.
  • RBAC overrides: If a chat is explicitly shared with a user, they can view it regardless of their public/private permissions.
API keys inherit the permissions of the user who created them. If the user’s role lacks access to the connector or resource being queried, the API call will fail with a 403 or 401 error.Solution:
  • Ensure the user’s role has access to the connector (via the Connectors page share settings).
  • If the user was recently changed from admin to member, allow up to 15 minutes for permission changes to propagate.
  • As a workaround, temporarily make the user an admin, generate the key, then revert. The key will retain the permissions it was created with.
Currently, only admin users can generate API keys from the Settings page.Solution: Temporarily grant the user admin access, have them generate the key in Settings > Developers > API Keys, then revert their role back to member. The API key will continue to work.

​
Sharing & Collaboration

All three content types use the same sharing model.Solution:
  1. When created, the item is private (only the creator can see it).
  2. You can share it with specific teammates as viewer (read-only) or editor (can modify).
  3. You can make it public so everyone in the organization can access it.
Use the Share button in the top-right corner of any thread, playbook, or dashboard.
To restrict certain users to read-only access on a playbook, use the playbook’s Share settings.Solution: In the playbook’s Share settings (top-right corner):
  1. Set the playbook to Restricted Access.
  2. Add specific users or roles with Viewer access.
Viewers can see the playbook and its results but cannot modify the prompt, schedule, or configuration.
There is no self-serve user export in the UI.Solution: Contact your TextQL account manager or email support@textql.com to request a user list export.

​
Authentication & SSO

Google Sign-In authentication failed error
This typically means the email on the Google account does not match the email registered to the TextQL account. Common causes:
  • The account was originally created with one email and later switched to a different one.
  • Google auth was never linked during initial setup.
To check which email the TextQL account is registered under, use the magic link login method. The login email will display the registered email:
Magic link email showing registered account email
Solution: Contact support@textql.com with your Google email and the TextQL account email to get them re-linked. For SSO configuration, see Single Sign-On (SSO).
TextQL supports SSO integration via Okta, Microsoft Entra ID, Google, Ping, and generic OIDC providers.Solution: Follow the Okta-specific setup guide at SSO - Okta. For general SSO configuration, see Single Sign-On (SSO).
This happens when billing information has not been set up for the organization. The onboarding flow prompts you to choose a plan and confirm payment.Solution: Complete the onboarding steps (plan selection and billing). If you are on a paid plan and still seeing this, contact support@textql.com — your billing configuration may need to be re-linked.

​
OIDC

When attempting to log in via SSO, you see a “Processing OIDC Login” screen with the following error:
OIDC access denied error showing: Identity provider error: access_denied - User is not assigned to the client application.
Your identity provider (e.g. Okta, Azure AD) has not assigned your user account to the TextQL application. This means your IdP is blocking the login before it ever reaches TextQL.Solution: Ask your organization’s Okta (or IdP) admin to assign your user account to the TextQL application within the identity provider. Once you’ve been added, retry logging in.

​
Pricing & ACU Consumption

ACU pricing is token-based and varies by model. The table below shows the ACU cost per 1M tokens (input and output) and the context window size for each available model:
ACU pricing table by model
Key things to keep in mind:
  • More powerful models tend to generate more tool calls per completion, which increases total tokens consumed and therefore cost per thread.
  • The default model (Sonnet 4.6) is the most cost-efficient for most use cases.
  • When testing a new model, start with shorter threads to gauge cost before committing to long analyses.
Solution: Use the default model (Sonnet 4.6) for most use cases to minimize costs. For the full pricing breakdown, see Pricing and Consumption Table.
Usage and spend reporting (active users, ACU consumption by user, monthly breakdowns) is currently available by request.Solution: Contact your TextQL account manager or email support@textql.com with the time range and level of detail needed (aggregated vs. per-user). For real-time ACU balance information, see Pricing.
If your organization’s credit balance is exceeded, the organization is suspended and users cannot access the service.Solution: Contact your TextQL account manager or email support@textql.com. Options include adding buffer credits while a contract renewal is in progress, or switching to unlimited usage pay-as-you-go billing with an invoice at end of month.
By default, there is no guardrail preventing users from asking questions unrelated to your data. Any prompt that Ana processes will consume ACUs.Solution: Add instructions to your organization context that restrict Ana to only answering questions relevant to your business data. Contact your TextQL account manager if you need help setting this up.

​
API & Documentation

The public API reference covers standard endpoints. Tenant-specific endpoints (e.g., /CreateApiKey, /ListRoles, /UpdateApiKey) are provisioned per organization and not listed in the public docs.Solution: Contact your TextQL account manager or email support@textql.com for documentation on tenant-specific endpoints. The public API reference is at docs.textql.com/api-reference.
The API authentication header format has changed from Authorization: ApiKey <key> to Authorization: Bearer <key>.Solution: Update all API calls to use the Bearer prefix instead of ApiKey. No changes to the key itself are needed.
The /CreateApiKey endpoint requires a role UUID, which is not visible in the TextQL UI.Solution: Use the ListRoles endpoint:
POST https://app.textql.com/rpc/public/textql.rpc.public.rbac.RBACService/ListRoles
Pass an empty body {} with your API key in the Authorization: Bearer <key> header. The response will include all roles with their UUIDs.

​
Data Storage & Security

For cloud deployments, TextQL processes queries in real-time and does not persist raw query results beyond the session. Thread history (prompts and responses) is stored for the user’s convenience.Solution: For detailed answers on data storage, retention, processing location, and compliance, see Security Whitepaper or contact support@textql.com for a formal data processing questionnaire.
Currently, each Snowflake role requires a separate connector. TextQL does not support dynamic USE ROLE switching within a single connection.Solution: Use Snowflake OAuth (user-level authentication via popup) for deployments where each user has their own Snowflake role. This allows per-user access control without creating a connector per role.

​
VPC / Self-Hosted Deployments

Error 321 credential refresh failure
This error indicates an IAM role misconfiguration for AWS Bedrock access in the hosting AWS account.Solution: Check the IAM role attached to the EKS nodes (typically named tql-eks-node-role or tql-eks-cluster-role) and verify:
  • The role has valid Bedrock permissions.
  • Credentials have not expired.
  • Rate limit / quota on the IAM role has not been exceeded.
Not applicable to cloud-hosted customers.
In VPC/EKS deployments, the database migration pod may fail silently with no log output.Solution: Contact TextQL support at support@textql.com for the latest Helm chart version, which includes updated logging for migration pods. Not applicable to cloud-hosted customers.
VPC deployments generate member_id and identity_id UUIDs in the hosted Postgres database. These can serve as pseudonymous identifiers that cannot be used to identify users without direct database access.Solution: Contact TextQL support to discuss rewiring the console to display UUIDs instead of email addresses, and to review what telemetry data is sent from your deployment. Not applicable to cloud-hosted customers.
To add a second domain (e.g., ringteam.com in addition to amazon.com), a user with an email on that domain must be the one to add it. This is a security feature to prevent unauthorized domain claims.Solution: Invite a user from the new domain via the Settings page. Once they log in, they can add their domain to the OIDC configuration. If this creates a deadlock (the user can’t log in without the domain being whitelisted), contact support@textql.com to have the domain added directly in the database.
VPC deployments may need to use organization-managed Anthropic or OpenAI endpoints rather than TextQL’s defaults.Solution: Contact your TextQL account manager to configure your VPC deployment to use your own Anthropic or OpenAI endpoints.
If pods are stuck in ImagePullBackOff, the Docker credentials used to pull TextQL images may have expired.Solution: Contact TextQL support at support@textql.com for updated Docker credentials or the latest Helm chart. Apply the updated credentials and restart the affected pods.
VPC deployments behind network firewalls need specific domains allowlisted for TextQL to function.Solution: At minimum, ensure the following are reachable from the VPC:
  • Docker Hub — for pulling container images
  • console.textql.com — for usage data reporting
  • Any domains allowlisted in the TextQL proxy (e.g., codecommit for sandbox operations)
Contact TextQL support for the full list specific to your deployment configuration.