Error Codes

Error Codes Reference

This page documents the errors returned by the laredo engine, config loader, and gRPC services. Use this as a diagnostic reference when troubleshooting failures.

Engine validation errors

NewEngine() validates the configuration and returns a list of errors if anything is misconfigured. The engine will not start until all validation errors are resolved.

Source errors

Error	Cause	Fix
`at least one source is required`	No sources were registered via `WithSource()`.	Add at least one source to the config or engine options.
`source ID must not be empty`	A source was registered with an empty string ID.	Provide a non-empty source ID (e.g., `pg_main`).
`source "<id>" must not be nil`	A source was registered with a nil implementation.	Pass a valid `SyncSource` implementation.

Pipeline errors

Error	Cause	Fix
`at least one pipeline is required`	No pipelines were registered via `WithPipeline()`.	Add at least one pipeline binding a source, table, and target.
`pipeline[N]: source ID must not be empty`	A pipeline has no source ID.	Set the `source` field in the table config.
`pipeline[N]: references unknown source "<id>"`	A pipeline references a source ID that was not registered.	Check that the source ID in the table config matches a configured source.
`pipeline[N]: table name must not be empty`	A pipeline has no table name.	Set the `table` field in the table config.
`pipeline[N]: target must not be nil`	A pipeline has a nil target.	Configure a valid target (e.g., `indexed-memory`, `http-sync`).
`pipeline[N]: buffer size must be positive, got <n>`	Buffer size is zero or negative.	Set `buffer.max_size` to a positive integer, or omit it to use the default.
`pipeline[N]: max retries must be non-negative, got <n>`	Max retries is negative.	Set `error_handling.max_retries` to zero or a positive integer.
`pipeline[N]: duplicate pipeline ID "<id>"`	Two pipelines have the same source, table, and target type combination.	Each pipeline must have a unique combination of source ID, table, and target type.

Snapshot errors

Error	Cause	Fix
`snapshot schedule must not be negative`	Snapshot schedule duration is negative.	Set `snapshot.schedule` to a positive duration or omit it.
`snapshot serializer is required when snapshot store is configured`	A snapshot store was provided but no serializer.	Configure a snapshot serializer (e.g., `jsonl`) alongside the store.

Config validation errors

Config.Validate() checks the HOCON config structure before building engine options.

Error	Cause	Fix
`at least one source is required`	The `sources` block is empty or missing.	Add at least one source to the config file.
`at least one table is required`	The `tables` array is empty or missing.	Add at least one table entry to the config file.
`tables[N]: source is required`	A table entry has no `source` field.	Set the `source` field to match a configured source ID.
`tables[N]: references unknown source "<id>"`	A table references a source not defined in `sources`.	Add the source to the `sources` block, or fix the source ID.
`tables[N]: schema is required`	A table entry has no `schema` field.	Set the `schema` field (e.g., `public`).
`tables[N]: table is required`	A table entry has no `table` field.	Set the `table` field (e.g., `config_document`).
`tables[N]: at least one target is required`	A table entry has an empty `targets` array.	Add at least one target to the table entry.
`tables[N].targets[M]: type is required`	A target entry has no `type` field.	Set the target `type` (e.g., `indexed-memory`, `http-sync`).

Source validation errors

Sources implement ValidateTables() which returns ValidationError values with structured error codes.

`ValidationError` structure

type ValidationError struct {
    Table   *TableIdentifier  // nil for source-level errors
    Code    string            // e.g. "TABLE_NOT_FOUND"
    Message string            // human-readable description
}

Known error codes

Code	Scope	Meaning
`TABLE_NOT_FOUND`	Table	The requested table does not exist in the source database.
`PERMISSION_DENIED`	Source	The source credentials lack required permissions (e.g., replication privilege).

These errors are returned during engine startup when validating that configured tables exist and are accessible.

gRPC error codes

The laredo gRPC services use standard Connect/gRPC status codes. Each service returns specific codes depending on the failure.

Error code summary

Code	Numeric	When returned
`InvalidArgument`	3	Required fields are missing or have invalid values.
`NotFound`	5	The requested resource (pipeline, source, target, snapshot, replay) does not exist.
`FailedPrecondition`	9	An operation requires a precondition that is not met (e.g., no snapshot store, missing confirmation).
`ResourceExhausted`	8	A resource limit has been reached (e.g., max replication clients).
`Internal`	13	An unexpected server-side error occurred.
`Unimplemented`	12	The RPC is not implemented.

OAM service errors

GetTableStatus, GetTableSchema

Code	Condition	Message
`InvalidArgument`	`schema` or `table` is empty	`schema and table are required`
`NotFound`	No schema data for the table	`no schema for <schema>.<table>`

GetPipelineStatus

Code	Condition	Message
`InvalidArgument`	`pipeline_id` is empty	`pipeline_id is required`
`NotFound`	Pipeline ID not found	`pipeline <id> not found`

GetSourceInfo

Code	Condition	Message
`NotFound`	Source ID not found	`source <id> not found`

ReloadTable

Code	Condition	Message
`InvalidArgument`	`source_id` is empty	`source_id is required`
`InvalidArgument`	Invalid table identifier	`invalid table: <error>`

PauseSync, ResumeSync

Code	Condition	Message
`InvalidArgument`	`source_id` is empty	`source_id is required`
`Internal`	Engine operation failed	(error from engine)

ResetSource

Code	Condition	Message
`InvalidArgument`	`source_id` is empty	`source_id is required`
`FailedPrecondition`	`confirm` is not `true`	`confirm=true is required for destructive operation`

CreateSnapshot

No specific error codes. If the engine rejects the snapshot, the response contains accepted=false with a message.

ListSnapshots, InspectSnapshot, DeleteSnapshot, PruneSnapshots

Code	Condition	Message
`FailedPrecondition`	No snapshot store configured	`no snapshot store configured`
`InvalidArgument`	`snapshot_id` is empty (Inspect, Delete)	`snapshot_id is required`
`InvalidArgument`	`keep` is not positive (Prune)	`keep must be positive`
`NotFound`	Snapshot not found (Inspect)	`describe snapshot: <error>`
`Internal`	Store operation failed	`list snapshots: <error>`, `delete snapshot: <error>`, `prune snapshots: <error>`

StartReplay, GetReplayStatus, StopReplay

Code	Condition	Message
`FailedPrecondition`	No snapshot store configured	`no snapshot store configured`
`InvalidArgument`	`snapshot_id` is empty	`snapshot_id is required`
`InvalidArgument`	Invalid table identifier	`invalid table "<table>": <error>`
`NotFound`	Replay ID not found	`replay <id> not found`

ListDeadLetters, PurgeDeadLetters

Code	Condition	Message
`FailedPrecondition`	No dead letter store configured	`no dead letter store configured`
`InvalidArgument`	`pipeline_id` is empty	`pipeline_id is required`
`Internal`	Store operation failed	`read dead letters: <error>`, `purge dead letters: <error>`

Query service errors

Code	Condition	Message
`InvalidArgument`	`schema` or `table` is empty	`schema and table are required`
`NotFound`	No indexed target for the table	`no indexed target found for <schema>.<table>`
`Internal`	Row serialization failed	(serialization error)

LookupAll

Code	Condition	Message
`InvalidArgument`	`schema` or `table` is empty	`schema and table are required`
`InvalidArgument`	`index_name` is empty	`index_name is required`
`NotFound`	No indexed target for the table	`no indexed target found for <schema>.<table>`
`Internal`	Row serialization failed	(serialization error)

Replication service errors

GetReplicationStatus, ListSnapshots (replication)

Code	Condition	Message
`InvalidArgument`	`schema` or `table` is empty	`schema and table are required`
`NotFound`	No fan-out target for the table	`no fan-out target for <schema>.<table>`

FetchSnapshot

Code	Condition	Message
`InvalidArgument`	`snapshot_id` is empty	`snapshot_id is required`
`NotFound`	Snapshot not found	`snapshot <id> not found`

Sync

Code	Condition	Message
`InvalidArgument`	`schema` or `table` is empty	`schema and table are required`
`NotFound`	No fan-out target for the table	`no fan-out target for <schema>.<table>`
`ResourceExhausted`	Max connected clients reached	`max clients reached`

Troubleshooting common errors

"at least one source is required"

The config file has no sources block, or the block is empty. Add a source:

sources {
  pg_main {
    type = postgresql
    connection = "postgresql://user:pass@localhost:5432/db"
  }
}

"references unknown source"

A table's source field does not match any key in the sources block. Check for typos:

sources {
  pg_main { ... }    # <-- source ID
}
tables = [{
  source = pg_main   # <-- must match
  ...
}]

"no snapshot store configured"

A snapshot operation was requested (via CLI or gRPC), but the server was not configured with a snapshot store. Add snapshot configuration:

snapshot {
  enabled = true
  store = local
  store_config { path = "/var/lib/laredo/snapshots" }
  serializer = jsonl
}

"confirm=true is required for destructive operation"

The ResetSource RPC requires explicit confirmation because it drops and recreates the replication slot. Pass --confirm when using the CLI:

laredo reset-source pg_main --confirm

"max clients reached"

The fan-out target has reached its maximum number of connected replication clients. Increase the limit in the target config or disconnect idle clients:

targets = [{
  type = replication-fanout
  grpc { max_clients = 1000 }
}]

"no indexed target found" / "no fan-out target"

A query or replication RPC was called for a table that does not have the expected target type. Verify that the table has an indexed-memory target (for query RPCs) or a replication-fanout target (for replication RPCs) configured.