Troubleshooting

Memory & ingestion

"The page is using too much memory"

DuckViz polls JS heap + IndexedDB + DuckDB every 10 s. When usage crosses the adaptive ceiling, a non-closable modal blocks further ingest until usage drops back to 90% (hysteresis).

Fix:

• Click a table in the memory popover (header badge) to unmount it
• Upload → Start fresh wipes the whole session
• Close other tabs, or bump the ceiling in Settings → Performance
• For hosts embedding packages: see Performance guide for defaultRowCap and largeFileWarnMB

DuckDB WASM fails to load

"Failed to initialize DuckDB" or a blank screen:

Fix:

• Check browser support — Chrome 90+, Firefox 89+, Safari 15.4+ (WebAssembly + Web Workers)
• Disable WASM-blocking extensions (some ad blockers / corporate security)
• Check network — DuckDB pulls its .wasm binary on first use
• Try incognito to rule out extensions

Slow ingestion for large files

Files over 100 MB take noticeable time but run in a Web Worker so the UI stays responsive.

Fix:

• Raise the batch size on <DuckvizDBProvider batchSize={10000}> for powerful machines
• See the ingest size matrix for realistic per-format limits
• Sample or split very large files before uploading

Persistence not restoring

Fix:

• Confirm persistence is enabled on <DuckvizDBProvider> (the app sets it from your settings)
• Private / incognito tabs usually clear IndexedDB on close
• Check browser storage quota — full quotas fail persistence silently

Logs & ingestion

Log files show up as "unparsed"

The file format matched either the 47-format catalog or an LLM-detected pattern, but some lines didn't fit.

Fix:

1. Select unparsed rows → Generate Pattern & Ingest
2. The selection is resampled; newly parsed rows are appended to the same table
3. If you own the format, save it as a custom format at /settings/log-formats — next time detection is local-only

"File format not recognized"

Extensions supported: .csv .tsv .xlsx .xls .json .jsonl .ndjson .xml .log .syslog .clf .evtx .parquet.

Fix:

• Rename with the right extension if known
• Compressed files (.zip, .gz): extract before uploading
• Parquet, CSV, JSON are all native DuckDB formats — they bypass the log parser entirely

AI & credits

"No credits" error on an AI action

Fix:

• Check the header badge balance
• Free features (SQL, uploads, exports, CLI push) don't cost anything
• Buy a credit pack — see Billing & Plans
• Failed requests auto-refund; retries are free

"I paid for credits but my balance didn't update"

Paddle topups are delivered via the /api/paddle/webhook handler, which is idempotent on the Paddle transaction id — the same transaction cannot topup twice.

Fix:

• Refresh the balance badge — it polls on nav, not every second
• Wait ~30 s; webhook delivery from Paddle is usually fast but can retry on transient errors
• Still missing after 5 min? Email support@duckviz.com with the Paddle receipt email — we can verify the webhook log on the server

Widget chart renders blank or wrong

Fix:

• Hit Refresh on the widget (re-runs the SQL)
• Expand the card to audit the SQL — a dropped table or renamed column is the usual culprit
• Chart aliases must match the CHART_REQUIRED_ALIASES contract — see Column alias contract. The dashboard rejects wrong-shape queries explicitly rather than silently rendering empty
• Try a different chart type via the chat prompt if the shape doesn't fit

Onboarding

How do I restart the welcome tour?

Go to Settings → Restart onboarding. This clears your step progress, removes the finished timestamp, and routes you to /home so the welcome hero reappears. Useful for walking a teammate through the flow or redoing it after dismissing too early. Full details: First-Time Experience.

The tour spotlight isn't lining up with the right panel

The Explorer tour highlights panels by ID. If you've got a layout extension or a browser zoom level that shifts the rendered panels mid-tour, the halo can end up off-target.

Fix:

• Reset zoom to 100% (Cmd/Ctrl + 0) and re-trigger the tour from Settings
• Disable browser extensions that inject UI into the page (some grammar / accessibility tools rewrite layout containers)
• If the halo doesn't appear at all, the spotlight gives up after ~30 frames and renders the card without it — the tour still works, it's just less guided

The checklist won't go away

The bottom-right checklist hides only when one of:

• You finish all 4 steps and click You're all set — finish
• You click × to dismiss it for this session/device (returns next sign-in)
• You restart onboarding from Settings (clears state) then dismiss

If it persists after restart, your browser is blocking localStorage writes for app.duckviz.com — check site settings.

Auth & tokens

"Invite link expired"

Confirmation links from Supabase expire after 24h. If yours doesn't work:

Fix:

• Open the sign-in page and enter your email → Resend confirmation (calls /api/auth/resend-confirmation)
• The new email invalidates any prior link
• For referral-invited accounts, /auth/reset drops you at /auth/set-password after confirmation

My PAT stopped working in the browser tab where I'm signed in

Bearer-first precedence. If a tab has a valid session cookie and is also sending Authorization: Bearer dvz_live_…, the bearer wins — requests auth as the token, not the user. Revoking the token (or sending stale bearer) surfaces as 401 even though you're logged in.

Fix:

• Don't wire PATs into a browser that's also signed in — keep bearer auth for servers / CI
• If a 3rd-party script injected the header, remove it
• Use the SDK from your backend instead

CLI browser tab never opens

Fix:

1. Copy the URL the CLI prints and open it yourself
2. Use --no-open (CLI 0.2.0+) to suppress the auto-open if you always do it manually
3. 10-min idle → server shuts down; re-run the command

Session & storage

Session data lost after browser update

Fix:

• Browser-level issue — DuckViz can't prevent it
• Export reports as PDF/DOCX for long-term keepers
• Re-push the files via CLI: npx duckviz ./data/

Something else?

Email support@duckviz.com with:

• Browser name + version
• Operating system
• Steps to reproduce
• Any console errors (F12 → Console tab)
• Approximate UTC time of the failure — helps grep server logs

We reply within 3 business days.