> Documentation index: https://docs.beetl.io/llms.txt # Troubleshooting > Common problems and how to fix them. Source: https://docs.beetl.io/troubleshooting/ Last updated: 2026-11-10 Common problems by area, with the likely cause and the fix. Look up any error code in the [error code index](https://docs.beetl.io/reference/error-codes), and caps such as file size in [Limits](https://docs.beetl.io/reference/limits). ## Getting started | Symptom | Cause | Fix | | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | Settings shows only the User tab | You are a TenantUser. Storage, AI, dashboards, external sources and Connect packages are admin settings. | Ask a TenantAdmin. To add a user or change a role, contact Beetl. | | "No object store configured", or `OBJECT_STORE_NOT_CONFIGURED` | Every tenant starts with Beetl's hosted store, so this only happens after all stores were removed. | A TenantAdmin adds one under Settings → Tenant → Object storage. The first store added becomes the default. | | Adding an object store fails | Beetl writes, reads and deletes a test object before saving, and a step failed. | Check the base URL, endpoint, region and keys, and that the keys may write, read and delete there. | | A dataset stays Pending | Nothing has been written to it yet, so it cannot be queried. | Run its sync, send a webhook delivery, or wait for its file processor to finish. | ## Connections and syncs | Symptom | Cause | Fix | | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | An integration is missing from New connection | Its Connect package is not installed or not **Ready**. | A TenantAdmin checks Settings → Tenant → Custom connection types. | | OAuth fails to start or the provider rejects the redirect | The popup was blocked, or the redirect URL is not registered with the OAuth app. | Allow popups for Beetl and register the [redirect URL](https://docs.beetl.io/sources/integrations#connecting-with-oauth). | | **Run now** is unavailable | The connection is not authenticated yet. A grey dot on Home means waiting for authentication or paused; hover to see which. | Finish the credentials or OAuth step, or choose **Resume**. | | **Reauthorization required** | The provider stopped accepting the authorization, and syncs stopped. | Open the connection and choose **Reconnect with OAuth**. | | A sync run failed | The Runs tab in the connection's details pane gives the reason. | Check the Logs tab. Failures in the integration's own code are not retried, so fix the cause and choose **Run now**. | ## Files and webhooks | Symptom | Cause | Fix | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | A file processor shows **Needs configuration** | Documents and spreadsheets need fields or a mapping before Beetl can read them. | Open the processor and finish its settings. See [Documents and spreadsheets](https://docs.beetl.io/sources/documents). | | A file processor shows a failed dataset update | Files in the set have different columns, or no longer match the dataset. Open the processor to read the reason. | Fix or remove the odd file, then choose **Process files**. | | A file is refused | It is empty, over 5 GiB, or has a different extension from the set's first file. | Split it, or give it a set of its own. | | A monthly export gained a column and processing fails | The dataset keeps its existing columns, and Beetl does not replace it. | Remove the odd file. For a document processor you can choose **Create a new dataset**, then point each pipeline's source at it. | | A webhook sender gets an error | Bad JSON, a missing or wrong token, a paused connection, or a body over 1,000,000 bytes. See [Responses](https://docs.beetl.io/sources/webhook#responses). | Fix the cause and resend. Refused deliveries are not kept. | | You lost a webhook token | The app shows it only once. | Create a new webhook connection for that sender. | | Webhook `payload` is unreadable | The JSON body is stored base64-encoded. | Decode it in SQL, as in [Check that data landed](https://docs.beetl.io/sources/webhook#check-that-data-landed). | | Adding a PostgreSQL source fails | The database must be reachable from the internet over TLS with a publicly trusted certificate, and the role needs `SELECT`. | Check host, port, certificate and grants, or export into a [File Set](https://docs.beetl.io/sources/file-sets). | ## Pipelines | Symptom | Cause | Fix | | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Preview failed under a stage | That stage's SQL failed; the message is under the cell. | Preview stages in order to find the first failure. | | Deploy is refused | No destination, a source showing **WARN**, or a missing `run.*` value. | Follow the message. See [Deploy and trigger](https://docs.beetl.io/pipelines/deploy-and-trigger). | | Deploy fails with a general error | The dry run failed. | Preview the last stage with the same run values to see the full message. | | **Run** is unavailable, or Deploy starts no run | Its tooltip names what is missing. Deploy starts no run when nothing changed or the pipeline is disabled. | Add what is missing, enable the pipeline, and press **Run**. | | A run fails after a column change | A destination keeps the columns and types of its first run. | Cast in the last stage, or write to a new destination. See [Schema compatibility](https://docs.beetl.io/pipelines/write-modes-and-partitioning#schema-compatibility). | | A Merge or predicate overwrite fails | 2 result rows match one destination row, or a row falls outside the predicate. | Deduplicate before the last stage, or fix the predicate. | | A source update starts no run | Trigger on update is off, the source is registered or external, or the pipeline was disabled. | Turn the trigger on, or run the pipeline by hand. | ## Queries and results | Symptom | Cause | Fix | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | A table is not found | The dataset is Pending or was renamed, or you are in a pipeline stage, which uses source aliases. | Check the current name with the Tables button or on Home. | | `Invalid function` or a signature error | The function is not in DataFusion, or got the wrong type. | See [Pitfalls](https://docs.beetl.io/query/datafusion-sql#pitfalls). | | `INSERT`, `UPDATE` or `CREATE` is refused | Queries are read-only. | Write data with a [pipeline](https://docs.beetl.io/pipelines). | | Results stop at 1,000 rows | A result stores the first 1,000 rows. | See [More than 1,000 rows](https://docs.beetl.io/query/export#more-than-1000-rows). | | "Result expired", or a result no longer opens | Results expire after 7 days. | Run the query again, or write the number to a dataset. | | A colleague cannot open your result | Results are private to whoever ran the query. | Send the CSV, or write a dataset. | | Drill-down is unavailable | Unsupported query shape, a registered or external source, or the dataset changed since the query ran. | Read the code shown for the cell. See [Lineage](https://docs.beetl.io/query/lineage#when-drill-down-isnt-available). | | Byte-limit error on an external table | A query pulls at most 64 MiB from external tables. | Filter more, or copy the data into a dataset with a pipeline. | ## Dashboards | Symptom | Cause | Fix | | ------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | Dashboards is greyed out | Dashboards are not set up, or not Active. | A TenantAdmin opens Settings → Tenant → Dashboards and sets them up or chooses **Retry provisioning**. | | A dashboard is missing or blank | It is a draft, embedding is off, a chart uses another database, or your Beetl address is not an allowed domain. | See [Superset embedding](https://docs.beetl.io/dashboards/superset-embedding#troubleshooting). | ## Chat and AI | Symptom | Cause | Fix | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | "You have reached your monthly AI limit" | Managed AI credits are used up until the 1st. | A TenantAdmin can register your own key, or contact Beetl about the plan. See [AI in a tenant](https://docs.beetl.io/concepts/ai-settings). | | The assistant stops mid-task | A turn runs for at most 20 minutes. | Ask it to continue in a new message. | | The assistant forgot earlier messages | Long conversations drop their oldest exchanges. | Start a new chat per topic. | | An automation run failed | The run's page gives the reason, such as no queryable data, no AI credits, or over 7 minutes. | Fix the cause, or split a heavy check. See [Automations](https://docs.beetl.io/automations#limits). | | Nobody noticed a failure or a Needs attention finding | Beetl shows status in the app and sends no email, Slack or webhook notifications. | Check the markers on Home and the Automations list filters, or poll `list_pipeline_runs` and `list_automation_runs` over MCP. | ## MCP | Symptom | Cause | Fix | | ------------------------------------------------- | ---------------------------------- | --------------------------------------------------------------- | | `401 MISSING_API_KEY` | No key was sent. | Send it in the `X-API-Key` header. See [MCP setup](https://docs.beetl.io/mcp/setup). | | `401 INVALID_API_KEY` | The key is unknown or was deleted. | Create a new key; an existing one cannot be shown again. | | A tool is missing, or a call fails naming a scope | The key has `read` scope. | Create a `write` key for that client. | | `get_query_result` refuses automation evidence | Evidence opens only in the app. | Open the run's page in Beetl. |