Skip to main content
Find the symptom below, then open its card for the exact message, the cause, and the fix. To look up a message you copied from a run, paste it into docs search (⌘K or Ctrl K). filament run ls <pipeline> shows recent runs, and the web app shows per-resource progress for each run.

​
Find your error

​
Pipeline setup

Cause. The source was created with --source-replication cdc, and filament pipeline create filled in its default read mode.Fix. Add --sync-mode cdc to filament pipeline create.
Cause. A CDC pipeline is running on a datastore that cannot track replication streams, such as the local SQLite CLI context.Fix. Run CDC pipelines on a deployment backed by the PostgreSQL datastore. See Deployment options.
Cause. Incremental reads need a primary key and a NOT NULL timestamp cursor that advances on every insert and update.Fix. Add a cursor column such as updated_at, choose an existing one for the resource, or use a full read.
Cause. CDC and incremental modes both require a primary key.Fix. Add a primary key, or copy the table with a separate full replace pipeline.

​
PostgreSQL CDC

Cause. Filament tried to create its publication, and the replication user lacks permission.Fix. Create the publication as a table owner, then set --source-manage-publication=false on the source:
Cause. Another client holds the pipeline route’s replication slot.Fix. Stop the other consumer or wait for the previous run to end.
Cause. Another client consumed WAL from the slot, so changes cannot be replayed.Fix. Re-snapshot the affected tables.
Cause. TRUNCATE on a tracked table fails the run.Fix. Re-snapshot the table.
Cause. The update arrived without the large column’s old value.Fix. ALTER TABLE <table> REPLICA IDENTITY FULL;
Cause. A replication slot is not being read, often from a deleted pipeline.Fix. Check pg_replication_slots and drop slots you no longer use. Filament stores each generated slot name in the control database’s replication_streams.consumer_name column.

​
MySQL CDC

Cause. Incompatible DDL changed the table after Filament cached its columns. Added nullable columns are handled automatically.Fix. Re-snapshot the table.
Cause. Binlog retention expired before the run read it.Fix. Keep retention longer than the gap between runs, then re-snapshot.
Cause. CDC needs a TCP connection.Fix. Use a user:pass@tcp(host:3306)/db DSN.

​
Snowflake

Cause. The account identifier does not match a Snowflake account.Fix. Set --sink-account to the organization-account identifier.
Cause. The public key on FILAMENT_USER does not match the private key, or the private key is encrypted.Fix. Set RSA_PUBLIC_KEY again from the .pub file, and pass an unencrypted PKCS#8 or PKCS#1 private key. See the Snowflake sink page.

​
BigQuery

Cause. The worker has no Application Default Credentials.Fix. Use Workload Identity on GKE, set GOOGLE_APPLICATION_CREDENTIALS on the worker, or run gcloud auth application-default login on a laptop, then restart the worker.
Cause. The service account lacks roles/bigquery.dataEditor or roles/bigquery.jobUser.Fix. Grant both roles as in Replicate PostgreSQL to BigQuery.

​
ClickHouse

Cause. ReplacingMergeTree removes older versions during background merges, not on insert.Fix. Query with FINAL, or run OPTIMIZE TABLE <table> FINAL.
Cause. The ClickHouse sink has no CDC, and incremental reads cannot see hard deletes.Fix. Schedule a full replace, or soft-delete with a column the incremental read picks up.
Cause. A pre-existing table’s engine, version column, or sorting key does not match what the write mode needs.Fix. Let Filament create the table, or match the engine and ORDER BY key described on the ClickHouse sink page.

​
Still stuck?

Ask in the Filament Slack community or open an issue on GitHub.