Troubleshooting
Troubleshooting
Common problems and how to fix them.
Common problems by area, with the likely cause and the fix. Look up any error code in the
error code index, and caps such as file size in Limits.
| 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. |
| 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. |
| 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. |
| 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. |
| 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. | 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
INSERT, UPDATE or CREATE is refused | Queries are read-only. | Write data with a pipeline. |
| Results stop at 1,000 rows | A result stores the first 1,000 rows. | See More than 1,000 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| Symptom | Cause | Fix |
|---|
401 MISSING_API_KEY | No key was sent. | Send it in the X-API-Key header. See 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. |
Last updated on
