Troubleshooting

Fix the most common pipeline and chart issues.

Almost every failure in the platform has a single root cause that appears as the first error in an execution log. Start there, not at the last line.

A method that always works

1
Open the failing execution log
Read from the top. The first error is the cause; everything after it is a consequence.
2
Reproduce on a small source
Upload a five row CSV that reproduces the shape of the real data and iterate on the transformation chain there.
3
Check the definition, not the data
Most “bad data” reports turn out to be a rename, filter or type step that no longer matches the upstream column names.

Pipeline run failures

Common run failures

Field	Type	Description
Pipeline already running	409 / 400	A pending or running execution exists for this pipeline. Wait for it, or cancel it first. The guard exists to prevent duplicate work.
No successful execution found	404	You opened analytics for a pipeline that has never completed a run. Run the pipeline and open it again.
No workspace is associated with this account	403	The account is not attached to a workspace, so nothing can be scoped. Create or join a workspace during onboarding.
Run time must be set when scheduling is enabled	400	Scheduling was switched on without a time of day. Set one, or disable scheduling.

Transformation errors

Transformation steps are validated when the pipeline is saved and re-checked when the run starts, so an error always names the step that failed.

Validation messages

Field	Type	Description
Step 2: 'value' is required.	400	A filter step has a column and operator but no comparison value. Every part of the comparison is mandatory.
Step 1: unsupported transformation_type 'explode'.	400	The step type must be one of filter, rename, convert_type or sort. Check for a typo in the step name.
Step 3: 'order' must be 'asc' or 'desc'.	400	A sort step received an unrecognised direction. Only ascending and descending are supported.
'customer_id' does not exist in the dataset.	run failure	The column was renamed or removed upstream. Rename the source column back, or update the step to the new name.
Could not convert column 'amount' to float	run failure	The column contains values that cannot be parsed as numbers such as currency symbols, thousands separators or text like 'N/A'. Clean them upstream or parse the raw text column.

Data source problems

Field	Type	Description
Unsupported file type	400	Only .csv and .json files can be sampled from the upload endpoint. Rename or convert the export.
Sample rows look wrong	—	The sample is read as UTF-8 text. A file exported in a legacy encoding will show mangled characters; re-export as UTF-8.
Header row treated as data	—	The first row is always used as the header. Remove any preamble rows before uploading.

Charts render nothing

The chart card shows an empty state. The selected dimension or measure produced no rows. Confirm both fields exist in the dataset and that the aggregation is meaningful for them.
Bars or lines sit at zero. The measure column is text, not a number. Add a convert type step and run the pipeline again.
A pie chart ignores most categories. Beyond eight slices the remainder is aggregated into a single Other bucket so the legend stays readable. Filter the dataset to reduce cardinality if you need a slice by slice view.
An old value is still displayed. Charts read the most recent successful run. Confirm the newest execution succeeded.

Access and workspace errors

Field	Type	Description
Invalid or inactive tenant	400	The workspace you selected was suspended or removed. Switch workspace from the header menu.
You do not have access to this tenant	403	The stored workspace no longer belongs to your account. Sign out and back in to refresh the workspace list.
Signed out unexpectedly	401	The refresh token expired or was revoked, or the password was reset. Sign in again; sessions last seven days unless rotated.
Forgot the password	—	Use Forgot password? on the sign-in screen. The emailed link is valid for 24 hours, works once, and resetting signs out every device.
Reset email never arrives	—	The request always reports success, so an unknown address looks identical. Confirm the address, check spam, then confirm with an operator that the account is active and the platform email settings are configured.

Platform and server errors

These originate on the server rather than in your data. Every one of them uses the canonical error envelope and carries an X-Request-ID header; see Conventions & Errors.

Server-side failures

Field	Type	Description
A run fails the moment it starts	503	The background worker was unreachable, so nothing was queued. The run is marked failed rather than left pending forever. Confirm the broker (Redis) and a Celery worker are running, then retry.
Charts and exports return 410	410	The stored result behind the chart was pruned. Re-run the pipeline to rebuild the dataset and the chart returns by itself.
Sign-in returns 429	429	Authentication allows 20 attempts per minute per client. Read retry_after from the response and wait that many seconds before trying once.
A request returns 500	500	An unexpected fault. The body is intentionally generic and never contains a stack trace or a database message. Quote the request_id to support.
Every request returns 503	503	A dependency is down, not your request. database_unavailable means the database is unreachable or unhealthy; dependency_unavailable means the cache, broker, object store or an upstream HTTP call failed. Both are transient and both carry retry_after in error and a Retry-After header, so client retries back off automatically. The session is deliberately kept, because the server never decided the session was invalid.

runserver exits with a Prometheus assertion

The API crashed on startup with the thread-based exporter assertion. The thread exporter and Django's autoreloader both want the same port, and runserver enables the autoreloader.

Startup crash

AssertionError: The thread-based exporter can't be safely used when
django's autoreloader is active. Use the URL exporter, or start
django with --noreload.

Metrics are served over HTTP from /metrics/ and scraped from there, so the port-range exporter is deliberately disabled. If you see this message you are on an older checkout - update it, and do not re-enable PROMETHEUS_METRICS_EXPORT_PORT_RANGE.

Signing in fails while Redis is down

Rate limiting needs a cache, and throttle classes fail open by design. When the cache is unreachable the platform logs the outage once per minute at ERROR and lets the request through, instead of locking every user out of the product.

Live log stuck on Reconnecting or Polling

The connection badge tells you which half is failing, and the two halves have different causes.

Symptom to cause

Field	Type	Description
Polling	string	No socket could be opened, usually because the Channels layer cannot reach Redis. Check the Redis host in CELERY_BROKER_URL (or CHANNEL_LAYER_URL). redis://redis:6379/0 only resolves inside Docker Compose; an API started with manage.py runserver on the host needs redis://localhost:6379/0. Progress is still updating while you fix this - the run is unaffected.
Reconnecting	string	The socket was established and then dropped. A proxy with a short idle timeout is the usual cause; confirm the WebSocket upgrade passes through to the ASGI server (daphne), not a WSGI one.
Offline, session ended	string	The access cookie expired and could not be refreshed. Signing in again re-opens the stream; the run keeps executing either way.

Diagnostics checklist

Order of checks

1. execution status        success / failed / cancelled
2. first log line           the root cause
3. transformation steps     names still match the columns
4. column types             numbers parse as numbers
5. latest successful run    what the charts are reading
6. workspace context        correct workspace selected
7. request_id (5xx only)   quote it to support

Last reviewed October 2026.