Errors and diagnostics

sqlstreams explain SQL0105

Looks up a SQLStreams error, log event, metric, or alert in the CLI’s compiled catalogue. It works without a database connection and includes diagnostic SQL when the declaration supplies it.

Identify a diagnostic

Kind	Where its code appears	Meaning
Error	Returned error text and structured `error.code`.	An operation failed. Recovery class describes whether an unchanged retry can succeed.
Log event	Log line’s `code` field.	A declared event occurred. The emission site determines its level.
Metric	Metric definition’s `Code` field.	Identity and interpretation of a measurement, not an error.
Alert	Alert definition’s `Code` field.	A condition evaluated from evidence. The report has its own active/resolved state.

Validation and underlying database errors do not necessarily have SQL codes. A log event code and a nested error code can describe different parts of one failure.

Handle returned errors

Using an initialized client, branch on the declared error for an absent payments.requested stream:

_, err := client.Stream[sqlstreams.RawPayload]("payments.requested").Producer().Register(ctx, nil)
if errors.Is(err, sqlstreams.ErrStreamNotFound) {
  return errors.New("register payments.requested before starting its producer")
}
if err != nil {
  return err
}

Use errors.Is against declared Err variables and errors.As to inspect a *sqlstreams.DiagnosticError. Do not branch on rendered problem or fix text.

DiagnosticError

Method	Returns	Contract
`GetCode()`	`string`	Declared SQL code.
`GetKind()`	`DiagnosticKind`	Error diagnostic kind.
`Recovery()`	`DiagnosticRecovery`	`RecoveryTransient` or `RecoveryPermanent`.
`Problem()`	`string`	Declared problem text.
`Fix()`	`string`	Declared fix, with placeholders still present. Can be empty.
`FixPlaceholders()`	`[]string`	Unique placeholder names in first-appearance order.
`Fill(text string)`	`string`	Substitutes attached values into placeholders.
`Queries()`	`[]DiagnosticQuery`	Detached diagnostic query values.
`With(pairs ...any)`	`*DiagnosticError`	Copy with attached name/value pairs.
`Wrap(cause error)`	`*DiagnosticError`	Copy with a wrapped cause.
`Values()`	`[]slog.Attr`	Detached attribute slice, preserving attachment order. Arbitrary nested values are not deep-copied.
`Error()`	`string`	Problem, attached values, filled fix, code, and optional cause.
`Unwrap()`	`error`	Wrapped cause, or `nil`.
`Is(target error)`	`bool`	Matches another `DiagnosticError` with the same code.
`LogValue()`	`slog.Value`	Structured error fields for logging.
`Docs()`	`string`	Documentation URL derived from the code.

With and Wrap leave the shared declaration unchanged. RecoveryTransient means an unchanged retry can succeed, not that it is always safe to repeat external effects after an uncertain outcome. RecoveryPermanent requires a change to the request or state before retrying.

DiagnosticEvent

Method	Returns	Contract
`GetCode()`	`string`	Declared SQL code.
`GetKind()`	`DiagnosticKind`	Event diagnostic kind.
`Message()`	`string`	Exact static log message, including its declared consequence.
`Queries()`	`[]DiagnosticQuery`	Detached diagnostic SQL entries.
`Docs()`	`string`	Documentation URL derived from the code.

DiagnosticQuery

Field	Type	Description
`Label`	`string`	What the diagnostic query investigates.
`Sql`	`string`	SQL template with resource placeholders.

Placeholders() returns unique placeholder names in first-appearance order.

Logging

Configure the sink through ClientConfig.Logger. The default logs Warn and Error to stderr. Pass error objects as structured attributes so their code, recovery, values, and cause remain available.

Consumer instances suppress repeated Warn/Error lines with the same level and static message for one minute. The first occurrence passes. The next occurrence after that window includes suppressed_count. Attributes such as message id do not separate suppression keys. Silence does not prove the condition stopped.

Operations using a log buffer retain recent lower-level records and attach them under preceding when an error occurs. This is diagnostic context, not a durable history of every operation.

CLI

sqlstreams explain
sqlstreams explain SQL0019 --output json
sqlstreams explain sqlstreams.consumer.cursor.backlog
sqlstreams explain ready_count
sqlstreams explain worker_liveness

With no argument, lists every declared diagnostic ordered by code. A code lookup is case-insensitive. Metrics also resolve by wire name or consumer stopped-log counter key. Alerts resolve by name. A successful lookup exits with status 0. An unrecognized lookup returns a usage error.

Queries are templates. Fill resource placeholders from the affected log or error before executing them. Explain itself executes no diagnostic SQL.

Producer logs — Production timing and partitions.
Consumer logs — Processing, claims, and result recording.
Worker logs — Lease ownership and worker ticks.
System logs — Registration, scheduling, metrics, and alerts.
Troubleshooting — Short investigation and correction procedures.