Troubleshooting

This page groups the failures you’re likely to hit, by where they appear. Each entry gives the symptom, the likely cause, and the fix.

If your issue isn’t here, the quickest path to an answer is to ask the Agent in-session — paste the error, ask for an explanation, and it’ll usually diagnose. Beyond that: support@tablize.com or the Discord community (link in the footer).

Getting started

”503 Service Unavailable” on first load

Cause: Tablize is still initializing. Domains bootstrap lazily on first request; the first page load can 503 for up to 30 seconds.

Fix: Wait 30 seconds and refresh. If it persists > 2 minutes:

• Cloud: check status.tablize.com.
• Self-hosted: docker logs tablize — look for migration errors or missing env vars.

Magic-link email never arrives

Cause: usually spam filtering.

Fix:

1. Check spam/promotions folder.
2. Add no-reply@tablize.com to contacts.
3. Self-hosted: verify SMTP_* env vars. Test with docker exec tablize tablize-cli test-smtp.

Uploading data

”File too large”

Cause: file exceeds your plan’s upload limit (50 MB on Free, 200 MB on Plus, 2 GB on Pro, 10 GB on Max).

Fix:

• Split the file into smaller chunks and upload separately; the Agent can UNION ALL them.
• Or convert to Parquet — same rows, 5-10x smaller on disk.
• Or upgrade the plan.

”Encoding error” / mojibake characters

Cause: the file claims UTF-8 but is actually Latin-1 / Windows-1252.

Fix: re-export from the source tool as UTF-8. In Excel: Save As → CSV UTF-8.

Date column typed as text

Cause: the first rows of the file have inconsistent or locale-dependent formats (e.g., 1/1/24 vs 01-Jan-2024).

Fix:

• Clean the source file.
• Or: ask the Agent: “parse the date_col column as dates with format DD/MM/YYYY.” It writes the SQL.

Connecting databases

”SSL connection required”

Cause: your DB requires TLS; the connection string doesn’t request it.

Fix: append ?sslmode=require to the connection string. For self-signed certs, use ?sslmode=no-verify.

”Permission denied for relation ”

Cause: the connection role can introspect the table (sees it in information_schema) but can’t SELECT from it.

Fix: grant SELECT explicitly:

GRANT SELECT ON <schema>.<table> TO tablize_reader;

Or exclude the table from introspection in connection settings.

Queries time out on large tables

Cause: full-table scan with no index.

Fix:

1. Add an index on the column you’re filtering by.
2. If the table is write-heavy in production, point Tablize at a read replica instead.
3. Self-hosted: raise statement_timeout for the Tablize role.

Integrations

This section is a user-facing distillation of the internal integration playbook. Specific known bug patterns are linked from there.

”Sync failed” with no data

Causes in order of likelihood:

1. Token expired. Check Integrations → the service → Health. A red indicator means reconnect via OAuth.
2. Permission revoked on the service side (user deleted the Tablize app, or admin revoked).
3. Rate limited by the source. Tablize backs off and retries automatically; sync eventually resumes.
4. Source API changed. We ship fixes in days; contact support if it persists > 72 hours.

Fix: for 1 and 2, click Reconnect on the integration page. For 3, wait. For 4, report to support.

Sync completes but row counts are wrong

Cause: cursor drift. Common when the source changes its updated_at semantics (Meta Ads and Amazon are repeat offenders).

Fix: in the integration’s Advanced tab, click Backfill from date and pick a start date. Tablize re-syncs that window.

”Credential not found” in chat

Cause: the Agent tried to use a stored secret that’s no longer in the vault.

Fix: Settings → Secrets → re-add. Secrets use their name as the stable reference — re-adding with the same name restores all references.

Date range error on initial sync

Cause: the source rejects start_date > end_date, which can happen if your workspace timezone differs from the source’s assumption.

Fix: set your workspace timezone explicitly in Settings → General. Then retry the initial sync.

Agent and chat

Agent returns “I couldn’t finish that — please try again”

Cause: a tool call timed out, or an upstream error (LLM provider 5xx) caused the turn to abort.

Fix: retry the exact same message. If it fails again, break it into smaller steps (“first do X, then Y”) — long multi-step turns are more likely to hit a timeout.

Agent keeps writing wrong SQL

Causes:

• Ambiguous column names (two tables have a status column and the Agent picked the wrong one).
• Bad schema labels (columns named col1, col2 with no documentation).

Fix:

• Add column comments in Postgres — the Agent reads them:

COMMENT ON COLUMN orders.status IS 'Order status: open|paid|refunded|void';

• Or be explicit in chat: “use orders.status, not users.status."

"Out of tokens” mid-question

Cause: your 5-hour rolling window saturated.

Fix:

• Wait (the window rolls continuously).
• Buy a top-up pack — applies instantly.
• Upgrade plan if this is a steady pattern.

See Billing & tokens.

Scheduled runs

Scheduled Report not appearing

Causes:

1. Lapsed payment. Check Settings → Billing.
2. Parameter evaluates to NULL. A relative time expression (last_monday()) needs a configured timezone.
3. Script error in the Report’s data block — run the data block manually to see the error.

Fix: Sidebar → Jobs → find the scheduled run → click to see status and error.

Watch not firing when you expect it to

Causes:

1. Threshold wrong. Click Test run on the Watch — shows the current value.
2. Debounce too long. If the condition is true for 3 minutes and the debounce is 5, it never fires.
3. Quiet hours. Check the schedule/quiet hours settings.
4. Acknowledged but not reset. If you acknowledged a previous firing, Watch is silent until condition resolves.

Fix: work through that list in order. The Watch detail page shows the last 50 check runs with their values, which usually reveals the issue.

Webhook integration lands 0 rows

Cause: payload shape doesn’t match what the Webhook is configured to expect.

Fix: Ingest → the Webhook → Recent deliveries → click any delivery → see what Tablize saw and why it didn’t parse. Most common: wrong content-type, or idempotency_key JSON path doesn’t exist in the payload.

IoT

No MQTT messages arriving

Causes:

1. Wrong broker host / port.
2. TLS enabled but device doesn’t support it (use port 1883 plain for test).
3. Credentials wrong.

Fix: Devices → the device → Recent messages. If the tab is empty, the handshake is failing — check docker logs emqx (self-hosted) or the device’s MQTT client log.

Messages arrive but don’t become rows

Cause: JSON parse error.

Fix: Devices → the device → Recent messages shows each raw payload and the parse result. Upload a decoder (Python function) if the device speaks a non-JSON format.

Camera frames not updating

Cause: RTSP stream stalled.

Fix: Assets → the camera → Reconnect. Tablize restarts the stream. For always-flaky feeds, increase the sample interval (less frequent samples = more resilient).

Apps and Dashboards

App shows blank after publishing

Cause: Data Contract references a query that works in dev but fails in prod (different data, different schema, permission).

Fix: App → Logs → see the failing query. The Agent can fix most Data Contract errors in one turn — describe the error, ask to repair.

Dashboard panel says “No data”

Causes:

1. Underlying query returns zero rows — check the time filter.
2. Underlying table was renamed or deleted.

Fix: click Repair on the panel — the Agent proposes a fix based on the current schema.

Embed in Notion shows nothing

Cause: Notion blocks iframes on some page types.

Fix: use the oEmbed URL instead of iframe. Notion renders oEmbed on all page types.

Self-hosted specifics

Can’t connect to Postgres from the Tablize container

Cause: Docker networking — usually DATABASE_URL references localhost instead of the service name.

Fix: use postgres://tablize:<pw>@postgres:5432/tablize (service name postgres, not localhost).

MinIO storage fills up

Cause: Media files retained longer than needed.

Fix: Settings → Storage → configure retention (default 30 days soft-delete + hard delete). Or use MinIO’s lifecycle rules to offload old files to an external bucket.

Tablize container OOM-killed

Cause: undersized host, or a runaway Python script in the sandbox.

Fix: increase host RAM to 16 GB, and set a memory limit on the Python sandbox container:

services:
  python-sandbox:
    deploy:
      resources:
        limits:
          memory: 2G

Escalation

Couldn’t fix it with the above? In order:

1. Ask the Agent — paste the error in a new chat. It often diagnoses issues it hasn’t seen before.
2. Search community Discord — link in the footer. Other users have hit most things already.
3. Email support@tablize.com with: your workspace ID, what you were trying to do, the error text, and what you’ve already tried. Response time: 1 business day on Cloud, 4 hours on Max.
4. For Enterprise customers: use your dedicated support channel (Slack or portal).

Next steps

• Billing & tokens — plan and token limits explained.
• Self-hosted — for self-hosted-specific ops issues.