Reference
Troubleshooting
Look up a symptom or an exact message, see its likely cause, and follow the link to the page with the full fix.
This page is an index. Find the message or the symptom you see, read its likely cause, and follow the link to the page that has the full fix. Messages appear as the product writes them; <...> stands for a value it fills in, and … for text it adds.
When a pipeline fails, start on its page. The banner, the Auto-restart card and the Logs tab name the first fault, and later faults are often a consequence of it. See Pipeline detail and Automatic restart. When you need SQL Flow support, collect a file with Download diagnostics first. See Diagnostics for support.
Connections and tests
Connection tests run on an agent, never on the control plane, so a failure describes the route from the agent's machine.
Connection tests in the wizard
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
Name does not resolve, Connection refused, No answer in time or Connection cut, with <agent> could not reach <host>:<port>. | The agent's machine can't reach that host and port. | Source: When the test fails |
| TLS handshake failed | Under Encryption at Require, the server doesn't offer TLS, the agent doesn't trust its certificate, or the name doesn't match. | Source: When the test fails, Logical replication, MySQL binlog |
| Login rejected | The server refused the credentials. | Source: When the test fails |
| Database not accessible | The database is offline, restoring or doesn't exist. | Source: When the test fails |
| A red alert box above the connection fields, and Next stays disabled | Host holds a pasted connection string, or for Oracle under Require a tcp:// address. | Source: Encryption |
| "Testing needs an online agent. Go back to step 1 and choose one (the control plane never connects to a database itself)." | No online agent is assigned. | Agent: When no agent is available |
| No online agent can capture <engine> | The online agents can't capture this engine. | Agent |
| "The source test connected but found no visible tables. …" | The login can't see any table in the database or service. | Tables and configure |
| A table is struck through with "No primary key or non-null unique index" | The table has no usable key. | Tables and configure |
| "This is the source database. Replicating into it would empty the source tables; choose a different target database." | The target points at the source database. | Target |
SQL Server 2016 SP2 (13.0.5026) or later (the source reports version <version>, …) | The SQL Server release is older than 2016 SP2. | SQL Server |
Secondary log consumer: another consumer already advances this database's replication truncation point; … | A CDC job or a replication publication already owns the truncation point. This is information, not a failure. | SQL Server DirectLog: Other log consumers |
Encryption, credentials and certificates
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
The <engine> connection names the secret reference 'env:<name>', but the environment variable SQLFLOW_SECRET_<name> is not set for this agent. | The variable isn't in the agent service's environment, or the service wasn't restarted. | Database credentials and secret references |
The <engine> connection names the secret reference 'file:<name>', but this agent has no readable secret file 'secrets/<name>' under its data directory. | The file is missing, misnamed or unreadable by the service account. | Database credentials and secret references |
'<reference>' is not a valid secret reference. | The reference doesn't start with env: or file:, or its name breaks the rules. | Database credentials and secret references |
Retired option, edit and save on a connection, or option 'trustServerCertificate' is retired or option 'sslMode' is retired | The connection carries an old option that the Encryption setting replaced. Edit and save it; on Azure SQL, remove the option. | Saved connections, Connections commands: Encryption, Azure SQL: Encrypted data |
encryption_not_applicable, or --encryption is not applicable to <engine> connections, which always validate the server certificate. Leave the flag out. | Azure SQL and SQL database in Fabric connections have no encryption setting. | Connections commands: Errors |
The Oracle connection requires TLS: enter the Server certificate DN of the listener's certificate. … | The Oracle connection has no Server certificate DN, under Encryption at Require or with a Wallet path on agent. | Oracle DirectLog, Oracle LogMiner |
This endpoint is a Fabric SQL analytics endpoint or Warehouse (engine edition 11), … | The connection names a read-only Fabric endpoint. | SQL database in Fabric |
This endpoint is an Azure SQL Database (engine edition 5), not a SQL database in Fabric. … | The server is Azure SQL, not Fabric. | SQL database in Fabric |
| A red alert with Start mirroring on a Fabric Mirror target | Mirroring is Initialized or Stopped. | Fabric Open Mirroring: Permissions |
The Google identity authenticated, but it cannot list Pub/Sub topics in this project (pubsub.topics.list is required for the target probe). | The agent's identity lacks pubsub.topics.list. | Google Pub/Sub: Permissions |
The Log broker panel
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
No log broker is registered for <host>. | No broker is installed for that host, or you entered an alias or address the broker didn't register under. | Broker: Read the panel |
| Awaiting approval | The broker registered and needs approval. | Log brokers: Approve a broker |
Broker on <host> is approved but not serving. | The control plane's reason follows, for example a log folder the broker doesn't serve. | Broker: Read the panel |
Discovered log path '<path>' is outside the log broker's allowed folders (<folders>) on host '<host>'. … | --allow-paths doesn't include the folder of the log file. | SQL Server DirectLog |
The source test found no transaction log file on this host. | The test couldn't discover the .ldf file. | Broker: Set the log file path |
Agents, brokers and relay
Installing and approving
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
Registration refused: the join code is spent, expired or unknown. | The code is older than 15 minutes, used, or from another control plane. | Agents |
Registration refused: this installation has been revoked. | The agent on this machine was revoked. | Agents |
No control-plane certificate authority is stored at <path>. | run started without a join code on an empty data directory. | Agents |
The agent log says identity <id> is awaiting approval | The agent isn't approved yet. | Agents: Approve an agent |
| Registration refused because the build is outside the version window | The release is too old or too new for the control plane. | Upgrades and restarts |
| A new agent or broker never appears on Agents | Outbound HTTPS to the control plane is blocked, or a firewall or proxy decrypts it to inspect it and presents its own certificate, which agents and brokers refuse. | Network and ports |
--allow-paths entry '<path>' does not exist or is not a directory | A folder is mistyped or doesn't exist on the host. | Log brokers |
--allow-paths value '<value>' contains a double quote. | A quoted Windows folder ends with a backslash. | Log brokers |
the C library of this host exports no statx (glibc 2.28 or later is required). | The Linux host's glibc is older than 2.28, so the broker can't serve log files. | Log brokers: Before you begin |
The broker log says Waiting for the approval in the control plane... | The broker isn't approved yet. | Log brokers: Approve a broker |
| Install says the broker's identity was revoked | The data directory holds a revoked identity. | Log brokers |
Agent and broker status
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
| The agent's chip reads Stale or Offline | No heartbeat for 30 or 60 seconds. | Agents and brokers |
| A red Revoked chip on an agent | Someone revoked the agent. Its credential is refused and it counts as stopped. | Agents and brokers: Approve, revoke and remove an agent |
| A version chip reads Upgrade soon, Support ended, Too new, Unsupported or Build denied | The release is outside the support window. | Agents and brokers: Version chips |
| Trust: not enrolled on an agent card | The agent holds no control-plane trust anchors. | Agents and brokers |
1 broker not reporting: <host>. … | The broker service has probably stopped. | Agents and brokers: Broker states |
| Pair readiness unconfirmed on a standby pair | An agent is offline, revoked, out of the version window, or lacks a connector, or went offline before it learned of the pair. | High availability: Agents |
| "This agent is reserved as standby. Remove its HA link before assigning or starting independent work." | A standby can't run pipelines of its own. | High availability: Agents |
| "This agent is running a source, relay, or apply role and cannot become a standby." | The agent still runs pipeline work. | High availability: Agents |
| "Agent '<id>' is not online, so it cannot acknowledge the stop. …" | You paused a pipeline from the UI while its agent is offline. An agent that doesn't answer may still be running. Use sqlflow pipeline pause --force, or revoke a lost agent. | High availability: Agents, Lifecycle: Forcing a pause or stop |
| "Agent … still holds a pipeline that has not acknowledged a stop, …" | Remove on an agent that isn't revoked and still holds a running pipeline. Revoke it first. | High availability: Agents |
| "To reassign this pipeline, dispatch Pause and wait for every runner to acknowledge it stopped." | The current agent hasn't confirmed the pause. | High availability: Agents |
Relay
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
Failed at tcp, refused or timeout | The capture agent can't reach the apply agent on the relay port. | Setting up relay agents |
Failed at dns | The capture agent can't resolve the relay host. | Setting up relay agents |
Failed at tls or identity | The host leads to a listener with another certificate. | Setting up relay agents |
Failed at pinned | A pipeline already uses the pairing's endpoint. | Setting up relay agents |
| "Port 7420 on … is already used by another pipeline." | Another pipeline uses the apply agent's listener. | Setting up relay agents |
| apply: reads not reported on the relay line | The apply agent hasn't sent a status. | Monitoring relay |
always_encrypted_relay_unsupported | Always Encrypted ciphertext copy needs local targets. | Distributed acceleration |
CLI and sign-in
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
error: Control plane login failed (401). Check the operator credentials. | Wrong email or password, or the user belongs to no account. | CLI overview |
Choose a new password before continuing. [password_change_required] | The user still has a temporary password. | CLI overview |
error: The SSL connection could not be established | The machine doesn't trust the control plane's certificate. | CLI overview |
You don't have permission to perform this action. | The user has the Viewer role. | CLI overview |
Too many requests from this client; retry later. [rate_limited] | More than 10 sign-ins in a minute from one address. | CLI overview |
Starting a pipeline and the initial load
The start is refused
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
Table <table> in <target> is also a target table of pipeline '<name>', which is <state>. … | Another active pipeline writes the same target table. | Lifecycle: Start |
Pipeline '<name>' was started on table <table> after this pipeline last wrote it, … | Another pipeline wrote the table while this one was paused. | Lifecycle: Start |
Another DirectLog pipeline of this source database is captured by agent <names>. … | All DirectLog pipelines of one database need the same capture agent. | Lifecycle: Start |
| Not started, not enough agent memory: | The agent can't hold the pipeline in memory. | Automatic restart |
Pipeline created, but Start was not confirmed. | The pipeline exists, but the agent didn't confirm the start. | Review and create |
Target table <name> does not exist in the target. Provision the target schema before starting the pipeline … | The target table wasn't created. | Prepare |
Target schema cannot be provisioned: the <target> target cannot hold <n> selected column… | A selected column has a type the target can't hold exactly. Each following line names the table and column, the reason and what to do: leave the column out, deselect the table or, for sql_variant, change the capture mode. | Data type mapping: When a column is refused, Data type support by engine |
target_bookkeeping_schema_not_ready: … | The target login can't create or use the bookkeeping schema. | SQL Server target: Permissions |
claim_ledger_shape_unsupported | The target holds an apply ledger left by an older release. | SQL Server target: The bookkeeping schema |
repair_source_snapshot_isolation_required or repair_source_row_versioning_required | A pipeline with processing rules needs ALLOW_SNAPSHOT_ISOLATION on the SQL Server source. | Validation and limits |
SQLFLOW_LOAD_WORKERS='<value>' is not a whole number between 1 and 64; … | The variable is out of range, so the agent doesn't start. | Initial load |
SQL Server and Azure SQL sources
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
marked capture for every tracked table (<n> tracked tables are not marked, …) | A DirectLog table isn't marked for capture. | SQL Server DirectLog |
The source database is not CDC-enabled. … | Mark now needs CDC on the database, which only a sysadmin enables. | SQL Server DirectLog |
The connection lacks the right to mark tables for capture … | The login can't run the marking. | SQL Server DirectLog |
max text repl size = -1 or 2147483647 (currently <value>; …) | A table has LOB columns and the server option is finite. | Large values and LOBs |
db_owner on the source database (sysadmin also passes). … | The DirectLog login isn't in db_owner. | SQL Server DirectLog |
DirectLog cannot prove that the source log is not TDE-encrypted. … | The login can't read the log's encryption state. | SQL Server DirectLog |
The source database uses Transparent Data Encryption (TDE), so DirectLog cannot read its transaction log. | DirectLog and Reconstruction can't read a TDE log. | SQL Server DirectLog: Encrypted data |
log-backup chain established (source reports FULL recovery but no base full backup has been taken, …) | No full backup since the switch to FULL recovery. | SQL Server DirectLog |
log_backup_compressed | A log backup the resume needs uses a compression the broker can't read. | SQL Server DirectLog: Log backups SQL Flow can read |
SQL Server DirectLog capture refuses at <lsn>: a TRUNCATE emptied tracked table <table> … | A tracked table was truncated after its marking was removed, or the capture can't tell which table a TRUNCATE emptied. | SQL Server DirectLog: Limitations |
always_encrypted_column: SQL Server capture refuses selected column … | A selected table has an Always Encrypted column. | Encrypted data support |
typed_xml_schema_collection: selected column <table>.<column> is XML(… | A selected column is xml typed by an XML schema collection, which no mode captures. | Data type support by engine |
Table '<table>', column '<column>' (sql_variant): sql_variant remains deferred for this capture: … | A Polling or Native CDC table has a sql_variant column, and the target is SQL Server or Azure SQL. Capture the table with DirectLog or Reconstruction, or deselect it. | SQL Server Polling, SQL Server Native CDC |
… (sql_variant): sql_variant remains deferred as a key column: …, or … for a sparse, computed, column-set or alias-typed declaration … | A sql_variant column is part of the key, or, under DirectLog or Reconstruction, is sparse, computed, in a column set or of an alias type, or sits in a table with Always Encrypted columns. Deselect the table. | Data type support by engine |
a decodable storage kind for tracked table <table> (the table is with a sparse COLUMN_SET: … | A DirectLog table has a column set, which SQL Server can't mark for capture. Drop the column set, or capture the table with Polling. | SQL Server DirectLog |
complete-row LOB fetch projection for table <table> (column '<column>' with SQL type '<type>' cannot be fetched: … | A DirectLog table with large values or wide rows has a column that can't be read back by key, such as a CLR user-defined type. | SQL Server DirectLog |
Tables with SPARSE columns and a dropped-but-not-rebuilt column are not supported in <mode> mode: … | A DirectLog or Polling table with sparse columns still holds a dropped column. Run ALTER TABLE <table> REBUILD, then start again. | SQL Server DirectLog: Limitations, SQL Server Polling: Limitations |
EXECUTE on the page-header helper dbo.sqlflow_page_header (this server has no sys.dm_db_page_info): … | On SQL Server 2016 SP2 or 2017, the helper procedure isn't installed, or the login can't run it. | SQL Server Reconstruction |
a signed page-header helper dbo.sqlflow_page_header (it exists and this login may execute it, but it cannot run DBCC PAGE: …) | The helper lost its signature, for example because someone altered it. | SQL Server Reconstruction |
Reconstruction cannot capture this source as configured: <n> requirement(s) are not met. | Settings, permissions or table shapes don't meet the requirements. | SQL Server Reconstruction |
Reconstruction refuses table <table>: it <reason>; … | The table has a shape Reconstruction can't capture. | SQL Server Reconstruction |
single transaction-log file (the database currently has <n> log files; …) | The database has more than one log file. | SQL Server Reconstruction |
DELAYED_DURABILITY=DISABLED on the source database (currently '<value>'; …) | Delayed durability is allowed or forced. | SQL Server Reconstruction |
sysadmin server role or db_owner database role (required for fn_dblog) | The Polling login has neither role. | SQL Server Polling |
VIEW SERVER PERFORMANCE STATE for Polling (VIEW SERVER STATE before SQL Server 2022): … | db_owner doesn't grant the log statistics read. | SQL Server Polling |
SELECT on sys.fn_dblog for Polling: … | The engine refused sys.fn_dblog. On SQL Server 2025, a db_owner login also needs a user in master with SELECT on it. | SQL Server Polling |
uncompressed rowstore for tracked table <table> under Polling (…) | The table is compressed. | SQL Server Polling |
recovery model=FULL (currently 'SIMPLE'; …) | The database isn't in FULL recovery. | SQL Server Polling |
sqlserver_polling_partition_truncate_refused | A partition TRUNCATE ran on a tracked table. | SQL Server Polling: Limitations |
CDC enabled on database (EXEC sys.sp_cdc_enable_db) | CDC isn't enabled for Native CDC. | SQL Server Native CDC, Azure SQL Native CDC |
Native CDC capture is incomplete for tracked table '<table>': no capture instance exists. … | A selected table has no capture instance. | SQL Server Native CDC |
Native CDC capture is not yet queryable for tracked table '<table>' … | The capture job hasn't scanned the new capture instance yet, or the login can't read every captured column. | SQL Server Native CDC |
native_capture_lob_replication_limit_unmet: … | A Native CDC table has LOB columns and max text repl size is finite. | SQL Server Native CDC |
native_capture_text_codepage_mismatch: … | A text column's code page differs from the database's. | Azure SQL Native CDC |
native_cdc_computed_column: Native capture refuses selected column <table>.<column>: … | A Native CDC capture instance includes a computed column. | SQL Server Native CDC: Limitations |
NativeCdcUnsupportedProviderType: column '<column>' of '<table>' has type '<type>'; … | A Native CDC table has a column of a CLR user-defined type. Remove the table from the pipeline. | SQL Server Native CDC |
sys.sp_cdc_enable_table fails with error 22854 | The table has a column set, which SQL Server's CDC doesn't support. Drop the column set, or capture the table with Polling. | SQL Server Native CDC: Limitations |
Oracle sources
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
Could not discover the DirectLog log-path candidates for this source | The login can't read the redo views, or the redo is in ASM. | Oracle DirectLog |
Oracle DirectLog prerequisite check failed before capture | A catalog view isn't granted, or the database isn't in ARCHIVELOG mode. | Oracle DirectLog |
The CDB root connection's login ... cannot see the source container | The common user's CONTAINER_DATA covers only the root. | Oracle DirectLog |
Oracle DirectLog supplemental-logging readiness failed before capture | Minimal supplemental logging or an (ALL) COLUMNS group is missing. | Oracle DirectLog |
Oracle DirectLog exact-LOB history is not ready for the required 3600-second horizon. | A LOB column isn't SecureFile with RETENTION MIN of 3,600 seconds and Flashback Database on, or RETENTION MAX. | Oracle DirectLog |
Oracle database character set '<name>' is not supported for raw value decoding. | DirectLog doesn't decode the database's character set. Use LogMiner. | Oracle DirectLog |
DirectLog does not yet reconstruct a re-chained LONG/LONG RAW row update … | An update spread a LONG or LONG RAW value over more than one block. Capture the table with LogMiner. | Oracle DirectLog |
oracle_long_prefetch_value_exceeds_allowance: complete bounded original-result LONG acquisition is required. | A LONG or LONG RAW value is larger than 16 MiB. | Oracle DirectLog, Oracle LogMiner |
Table <schema>.<table> has a <type> column "<column>", which Oracle lists as unsupported by DBMS_LOGMNR: … | The table has a BFILE, REF, nested-table, ANYDATA-family or URI-type column, which neither mode captures. Remove the table from the pipeline. | Oracle DirectLog, Oracle LogMiner |
Oracle DirectLog undo-retention readiness failed before capture | Undo retention is under 3,600 seconds or not guaranteed. | Oracle DirectLog |
Oracle DirectLog online tail is unavailable ... online redo tail supports exactly one enabled thread | The database runs more than one redo thread (RAC). | Oracle DirectLog |
oracle_archive_fence_privilege_required: The configured Oracle root connection requires ALTER SYSTEM for ALTER SYSTEM ARCHIVE LOG CURRENT. | A table resync, a key repair or a pipeline with processing rules needed a log switch, and the capture user lacks ALTER SYSTEM. | Oracle DirectLog |
Oracle CDC reader is missing privileges / settings | A LogMiner grant or setting is missing. | Oracle LogMiner |
LogMiner cannot mine a PDB source from inside the PDB (ORA-65040) | Root service for capture names the PDB rather than the CDB root. An empty one is refused earlier, by the source test. | Oracle LogMiner |
Table ... has a 23ai native BOOLEAN column | LogMiner can't capture native BOOLEAN, JSON or VECTOR columns. | Oracle LogMiner |
Table <schema>.<table> has an extended-width <type>(<length>) column "<column>" (MAX_STRING_SIZE=EXTENDED). … | A VARCHAR2 or NVARCHAR2 column is wider than 4,000 bytes, or a RAW column wider than 2,000 bytes. | Oracle LogMiner |
Oracle XMLTYPE text projection requires catalog-proven CLOB storage; … | An XMLTYPE column uses binary or object-relational storage. | Oracle LogMiner |
| LogMiner capture stops on a value it can't show | LogMiner printed a placeholder instead of a value, for example for an encrypted column while the TDE keystore is closed. Open the keystore and restart the pipeline. | Oracle LogMiner: Limitations |
| A table in a TDE-encrypted tablespace, or with encrypted columns or LOBs, is refused under DirectLog | DirectLog has no decryption step. Capture the table with LogMiner. | Oracle DirectLog: Encrypted data |
PostgreSQL, MySQL and Sybase ASE sources
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
PostgreSQL source-safety admission refused because max_slot_wal_keep_size is not a finite positive source-side WAL ceiling | WAL retention is unbounded. | Logical replication |
Postgres CDC reader is missing privileges / settings | A setting or privilege is missing, such as wal_level=logical or replication rights. The login gets replication rights from the REPLICATION attribute or from a replication role such as rds_replication. | Logical replication |
must be owner of table | The role can't add the table to the publication. | Logical replication |
Cannot create replication slot '<slot>': all <n> replication slots are in use | The server has no free replication slot. | Logical replication |
PostgreSQL logical replication slot '<slot>' already exists | A slot with SQL Flow's name was left behind. | Logical replication |
UPDATE or DELETE fails on the source with does not have a replica identity | A published table has no primary key or replica identity. | Logical replication |
MySQL CDC reader is missing privileges / settings | A binlog setting or replication privilege is missing, or binlog_row_value_options isn't empty. | MySQL binlog |
Unsupported column type: <type> (0x<code>) | A captured MySQL table has a column type SQL Flow can't decode from the binlog, such as VECTOR. Remove the table from the pipeline. | MySQL binlog |
Encountered a PARTIAL_UPDATE_ROWS_EVENT (binlog event type 39). … | binlog_row_value_options was set to PARTIAL_JSON after the pipeline started. Clear it, then reload the pipeline. | MySQL binlog |
Auth plugin '<plugin>' is not supported | The capture user uses another authentication plugin. | MySQL binlog |
Sybase CDC reader is missing privileges / settings | The Sybase login lacks replication_role (or sa_role), or under Reconstruction can't run checkpoint. | Sybase ASE DirectLog, Reconstruction |
ASE native log layout is unapproved. Supported build: … or ASE native log page size <size> is unapproved. | The server isn't the one ASE build SQL Flow decodes, or its page size isn't 16 KB. | Sybase ASE: Supported versions |
ASE loginfo(dbid, 'root_page') returned 0. … | The database's log shares a device with its data. | Sybase ASE DirectLog |
Sybase managed broker access requires a finite device length; raw devices reporting length 0 are unsupported. | A database device is a raw device. | Sybase ASE DirectLog |
Marked source has a configured or running RepAgent. | The database is replicated by SAP Replication Server. | Sybase ASE DirectLog |
Marked source table is already marked without product ownership. | Another product marked the table for replication. | Sybase ASE DirectLog |
| A Sybase table with an encrypted column, or an encrypted database, is refused at start | Neither mode decrypts. | Sybase ASE: Encrypted data |
Compressed or unknown ASE storage is not decoded. | The table is compressed. | Sybase ASE DirectLog, Reconstruction |
ASE server character set '<name>' is unsupported; refusing a replacement encoding. | SQL Flow can't decode the server's character set. | Sybase ASE: Supported character sets |
LOB chain exceeded 4096 pages; refusing to walk a runaway/corrupt chain. | A Reconstruction text, unitext or image value spans more than 4,096 pages, or its page chain is damaged. | Sybase ASE Reconstruction |
Invalid ASE schema metadata for column '<column>' (colid=<n>, declared='<type>', physical=0x<code>): … | A column has a storage type SQL Flow doesn't decode. | Data type support by engine |
The initial load
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
| The Initial load card stays at Waiting for the log broker | The broker isn't serving the log to the agent. | Broker, High availability: Log brokers |
The status chip reads queued, with Queued behind <pipeline names> for <time> | The load waits for resources that another load on the agent holds. Nothing is wrong. | Initial load: Loads that share resources |
| A table with large values is refused because the target has triggers | The streamed large-value load needs your consent. | Large values and LOBs |
| Target rows were replaced by the first start | A first start empties tables that hold rows and loads them again. | Initial load: Rows already in the target |
target_initial_load_ownership_unproven: … | A SQL Server, Azure SQL or SQL database in Fabric target table holds rows that SQL Flow has no load record for, so it won't empty it. Empty the table yourself, then start again. | Initial load: Rows already in the target |
| Every table loads again after you changed the pipeline's source | A new source host, port or database starts a new capture. Adding a table loads only that table. | Changing tables: What the next start does |
Streaming and lag
Pipeline status and restarts
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
| Pipeline failed, restarting automatically:, or the status Restarting | A transient fault, such as a lost connection or throttling. The agent restarts the pipeline. | Automatic restart |
| Failed, needs operator:, with the card reading Failed: needs operator | A terminal fault, or five restarts within 30 minutes. | Automatic restart: Resume a parked or failed pipeline |
The fault unrecognized-log-record, with Download diagnostics on the banner | SQL Server DirectLog met a log record it doesn't recognize and stopped right before it. | Automatic restart: An unrecognized log record |
Refusal evidence recorded: log block <block>, <date> on the banner | SQL Server capture refused a log block and kept a record of it on the agent for support. | Diagnostics for support |
| Target unreachable, Target throttling writes or Target permission denied | The target doesn't accept writes. Changes wait in the spool. | Automatic restart: Target outages |
| Nothing applied to the target: | Changes were captured, but none reached the target. | Pipeline detail: Banners |
| ⚠ Agent offline, or the status reads Stale | The agent that runs the pipeline is offline. The UI doesn't pause, archive or move its pipelines until it's back. Pause with sqlflow pipeline pause --force, or revoke a lost agent. | High availability: Agents |
| Log broker access unavailable: | The agent can't reach the log broker. | High availability: Log brokers |
The pipeline restarts with azure-paused | A serverless Azure SQL database is resuming. | Azure SQL Native CDC |
pipeline_owner_superseded | A write from an agent that lost its role was refused after a takeover. | High availability: Agents |
relay_capture_epoch_superseded | An older capture agent came back after a newer one took over. | How relay works |
Lag and the spool
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
| The lag figure is amber or red | Lag is past the bands for the pipeline's lag goal. | Lag, spool and log retention |
| Last source event reads capture may be stalled | The source reports changes that capture hasn't seen for over a minute. | Pipeline detail: Headline metrics |
| Last source event reads apply may be behind | Captured changes weren't applied a minute after the last one arrived. | Pipeline detail: Headline metrics |
Change spool shows backlog: <n> ↑ growing | The target is falling behind the source. | Lag, spool and log retention: The spool |
Degraded with spool_full_paused | The spool reached its limit, and SQL Server DirectLog capture waits on the source log hold until apply frees space. | Lag, spool and log retention: When the spool reaches its limit |
Degraded with spool_volume_full | The agent's data volume has less than 256 MiB free. Capture resumes by itself when space returns. | Lag, spool and log retention: Plan the disk |
The pipeline fails with a retention-gap fault after a warning that the spool reached its limit | The spool dropped changes the target hadn't applied. Free disk space, then select Actions > Reload from source. | Lag, spool and log retention: If the spool reseeds |
retention-cap-underivable: … or retention-cap-unworkable: … | The agent's data volume can't back a workable spool, so the pipeline doesn't start. | Lag, spool and log retention: Plan the disk |
| Relay backlog: growing, or capture spool growing with wire at zero | The apply side or the link can't keep up, or is down. | Monitoring relay: What to watch |
SQL Server Polling source busy: <n> consecutive retries of the same read window failed … | The server was too busy to return the log window. | SQL Server Polling |
SQL Server Polling source busy: the Polling window probe after <lsn> waits on an open DDL or TRUNCATE transaction (1222). … | An open transaction on the source holds a DDL change or a TRUNCATE. | SQL Server Polling |
Source log and retention
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
source_log_hours_to_loss | A SQL Server DirectLog pipeline that holds the log may reach its hold budget within 24, 6 or 1 hours, whether or not it is capturing. | Lag, spool and log retention: Hold alerts |
source_log_hold_budget_exceeded | The log reached 85 % of its capacity, so SQL Flow released the hold. | SQL Server DirectLog |
source_truncation_point_held_by_another_session | Another session is the database's log reader. | Source log retention |
source_log_gone_after_pause: … | The log was truncated during the pause, and no readable log backup covers the gap. | SQL Server DirectLog |
log_backup_chain_gap, or source_log_resume_may_need_reload, when you pause | No log backup SQL Flow can read covers a later resume. | SQL Server DirectLog |
log_reuse_wait_desc stays REPLICATION after you deleted a DirectLog pipeline | The delete couldn't release the marking. | SQL Server DirectLog: The log keeps growing after a pipeline was deleted |
Reconstruction halted [<label>] on <table> at LSN <lsn>: … | An operation Reconstruction can't carry exactly, such as a layout-changing index rebuild, an index REORGANIZE or a partition TRUNCATE. A halt needs Reload from source, as the message says. | SQL Server Reconstruction |
Reconstruction halted [F5 retention-gap] … | Log the capture needed was truncated, and no readable backup covers it. | SQL Server Reconstruction |
Transaction log truncated past the reader: … | A Reconstruction start found its saved position gone. | Lag, spool and log retention: Source log retention |
SQL Server Polling retention gap: … | Log records were truncated before Polling read them. | SQL Server Polling |
The source principal cannot execute sys.fn_dump_dblog for the selected backup set., or … cannot inspect the selected backup's actual media header. | The login can't read log backups after a gap. | SQL Server Polling |
Native CDC retention gap for tracked table '<table>' … | CDC's cleanup removed change rows the pipeline hadn't read. | SQL Server Native CDC |
unrecoverable redo gap for Oracle DirectLog group | An archived log was deleted before DirectLog read it. | Oracle DirectLog |
No redo/archive log files found for SCN range | Archived logs LogMiner needs were deleted or moved. | Oracle LogMiner |
Replication slot '<slot>' was invalidated by PostgreSQL … | The slot retained more WAL than max_slot_wal_keep_size. The message ends with the fix: reload the pipeline, and raise max_slot_wal_keep_size. | Logical replication |
The established PostgreSQL capture slot is missing; … | The slot was dropped, or the source is another server. | Logical replication |
MySQL binlog resume position purged (error 1236) | The binlog file the pipeline needs is gone. | MySQL binlog |
the transaction log was truncated past the capture resume position | The Sybase log was truncated while not held. | Sybase ASE DirectLog, Reconstruction |
The agent log warns that trunc log on chkpt is enabled | ASE can truncate log a paused pipeline still needs. | Sybase ASE DirectLog, Reconstruction |
Schema changes
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
| A Schema review card lists a table as paused: awaiting review | The target can't apply a source schema change by itself. Other tables keep streaming. | Schema changes: Held schema changes |
| A review reads paused: awaiting resync | The DDL ran on the target, and the table needs a fresh copy. | Reviewing held changes: Resync the table |
SQL Server log-native schema history gap for '<table>': … | A change SQL Flow can't carry exactly, such as a type change, a table rename, or an added column of typed xml or of a CLR user-defined type. A restart, or Pause then Start, stops at the same change, even after you undo it on the source; select Reload from source. | Schema changes, SQL Server DirectLog |
| An index rebuild stops the pipeline | The rebuild moved rows in a way the capture can't follow exactly. | Supported changes: Index changes |
INCOMPATIBLE, or blocked · source schema changed, on the Schemas page | The capture no longer matches the source table. Reload the table, as the statement says. | Schema events |
Targets
Writing to the target
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
Tracked table '<table>' (pipeline '<id>', target engine '<engine>') has no primary key or unique key resolved on the target, … | The target table has no key on the source key columns. | PostgreSQL target, MySQL target |
| A PostgreSQL, MySQL, Oracle or Sybase ASE permission error stops the pipeline | The target login lacks a privilege; these targets have no privilege check up front. | The target's Permissions section, for example PostgreSQL |
PostgreSQL major <n> is outside mapping contract v<n>. | Tables from a SQL Server or Oracle source need PostgreSQL 14 to 18. | PostgreSQL target |
This target derives row identity from the source key; startup is refused … | A table published to Kafka has no primary key on the source. | Kafka |
Kafka event for '<table>' is larger than the 1,000,000-byte message limit. …, or Serialized Kafka event is approximately <n> bytes, over the 1,000,000-byte message limit for topic '<topic>'. | One change exceeds Kafka's message limit, which can't be raised. Leave the large column out with output columns. | Kafka |
Pub/Sub event for '<table>' (<operation>) exceeds the 10,000,000-byte service limit. … | One change exceeds Pub/Sub's message limit. Leave the large column out with output columns. | Google Pub/Sub |
Open Mirroring has no __rowMarker__ that expresses a TRUNCATE, … | A source TRUNCATE can't be forwarded to Fabric. | Fabric Open Mirroring |
restart '<id>' of table '<table>' needs its landing folder '<folder>' deleted first, … | A Fabric table re-seed started while the table's folder still holds files. | Fabric Open Mirroring: Re-seed one table |
Pipeline <id>: Reload isn't available for <engine> targets, because published events and files can't be withdrawn. … | Kafka, Pub/Sub and Fabric Mirror can't be reloaded. | Lifecycle: Reload |
always_encrypted_target_route: encrypt requires ordered scalar apply … | Encrypting into Always Encrypted columns needs ordered apply. | SQL Server target: Always Encrypted targets |
Table <table> in <target> would be written by <n> targets of this pipeline (<ids>). … | Two targets of one pipeline write the same table. | Multiple targets |
Compare and repair
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
The pipeline is <status>. Compare needs it streaming: … | The pipeline isn't streaming: it is loading, restarting, paused or in a dry run. | Compare |
| The Data drift: target differs from source alert | A compare confirmed rows that differ. | Repairing drift |
a key omits primary-key column '<column>' | A JSON key doesn't name every key column. | Repairing drift |
resync_fk_cutover_unsupported | The resync would empty a table that has, or is referenced by, a foreign key on the target. | Repairing drift: Resync a table |
| A key repair or resync with a SQL Server Native CDC source is refused before it starts | The source login can't run sys.sp_repltrans. db_owner has the permission. | Repairing drift: Before you begin |
| Scheduled key repair skipped or Scheduled key repair not completed | The automatic repair policy couldn't repair the drift a compare found. | Automatic repair policy: Alerts |
Diagnostics for support
| Symptom or message | Likely cause | Where to fix it |
|---|---|---|
… requested less than a minute ago. Try again in <wait>., Diagnostics were requested too often. … or Raw log bytes for this pipeline were exported a short while ago. … | Requests are limited to one diagnostics file per pipeline per minute and 20 per account per hour, and one raw export per pipeline per 10 minutes. Wait the time the message gives. | Diagnostics for support: Troubleshooting |
An amber strip: Diagnostics downloaded without <agent>'s part: <reason>. … | An agent was offline or too old to deliver its part. Send the file anyway. | Diagnostics for support: If part of the file is missing |
| Save raw log bytes on agent (contains row data)… isn't in the Actions menu | You aren't an Account admin of the pipeline's account, or no agent holds raw bytes for a stop. | Diagnostics for support: Save raw log bytes on the agent |
| You can't find the saved raw export | It is on the agent's host, at the path the strip shows, under support-exports in the agent's data directory, for up to 24 hours. | Diagnostics for support: Find the file on the agent |
