{"record":{"id":"94b4e5f9869b3f17","repo":"gastownhall/beads","slug":"errquery","errorCode":"ErrQuery","errorMessage":"query error","messagePattern":"query error","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dolt/errors.go","lineNumber":25,"sourceCode":"\t\"os\"\n\t\"path/filepath\"\n\t\"strings\"\n\n\tmysql \"github.com/go-sql-driver/mysql\"\n\n\t\"github.com/steveyegge/beads/internal/storage\"\n\t\"github.com/steveyegge/beads/internal/storage/dberrors\"\n)\n\n// Sentinel errors for the dolt storage layer.\n// These complement the storage-level sentinels (storage.ErrNotFound, etc.)\n// with dolt-specific error types.\nvar (\n\t// ErrTransaction indicates a transaction begin/commit/rollback failure.\n\tErrTransaction = errors.New(\"transaction error\")\n\n\t// ErrQuery indicates a database query failure.\n\tErrQuery = errors.New(\"query error\")\n\n\t// ErrScan indicates a failure scanning database rows into Go values.\n\tErrScan = errors.New(\"scan error\")\n\n\t// ErrExec indicates a database exec (INSERT/UPDATE/DELETE) failure.\n\tErrExec = errors.New(\"exec error\")\n\n\t// ErrDanglingReference indicates that the pre-push integrity check detected\n\t// missing chunks in the local Dolt noms store. The push was aborted to\n\t// prevent propagating the corruption to the remote. Run bd dolt verify\n\t// to diagnose and recover.\n\tErrDanglingReference = errors.New(\"dangling chunk reference\")\n\n\t// ErrFSCKTimeout indicates that the pre-push integrity check (dolt fsck) did\n\t// not complete within the configured timeout. The push was aborted without\n\t// verifying chunk integrity — the store is not necessarily corrupt. Large\n\t// stores can be shrunk with `dolt gc` (or `CALL DOLT_GC()` on a running\n\t// sql-server); the timeout can be raised via the BEADS_FSCK_TIMEOUT","sourceCodeStart":7,"sourceCodeEnd":43,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/errors.go#L7-L43","documentation":"ErrQuery is the dolt storage layer's sentinel for database query failures — the SQL SELECT itself failed (as opposed to scanning rows or executing writes). wrapQueryError embeds it in the error chain so callers can classify with errors.Is.","triggerScenarios":"Any dolt-backed read whose db.QueryContext/QueryRowContext returns an error: connection refused or dropped, table doesn't exist (1146, e.g. pre-migration database), syntax/schema mismatch after version upgrade, server timeout, or context cancellation mid-query.","commonSituations":"Pointing bd at a server serving a different data directory (wrong database); database not yet migrated (missing tables); server restarted or moved ports; transient network failure between client and dolt sql-server.","solutions":["Unwrap and inspect the underlying error: errors.As(err, &mysql.MySQLError) for the MySQL error number","Check server reachability and that the right database is being served (bd dolt status, bd doctor)","If the error is 'table doesn't exist' (1146), run migrations or bd bootstrap for a fresh clone/branch-switch","Retry on transient causes (connection reset, context deadline) once the connection is healthy"],"exampleFix":"// before\nissues, err := store.List(ctx) // 'query error: ...' — cause unknown\n// after\nissues, err := store.List(ctx)\nif err != nil {\n    var mysqlErr *mysql.MySQLError\n    if errors.As(err, &mysqlErr) && mysqlErr.Number == 1146 {\n        return nil, fmt.Errorf(\"database not migrated; run bd bootstrap: %w\", err)\n    }\n    return nil, err\n}","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"func isQueryError(err error) bool {\n    return errors.Is(err, dolt.ErrQuery)\n}\nfunc isTableNotExist(err error) bool {\n    var mysqlErr *mysql.MySQLError\n    return errors.As(err, &mysqlErr) && mysqlErr.Number == 1146\n}","tryCatchPattern":"if err := store.Get(ctx, id); err != nil {\n    switch {\n    case errors.Is(err, storage.ErrNotFound):\n        return nil, err\n    case errors.Is(err, dolt.ErrQuery) && isTableNotExist(err):\n        return nil, fmt.Errorf(\"run bd bootstrap / migrate: %w\", err)\n    case errors.Is(err, dolt.ErrQuery):\n        return nil, fmt.Errorf(\"query failed; check server health: %w\", err)\n    }\n    return err\n}","preventionTips":["Check errors.Is(err, dolt.ErrQuery) and errors.As(*mysql.MySQLError) for root cause","Verify server address/port/database match after any restart or branch switch (bd dolt status)","Ensure migrations run before reads on a fresh clone (bd bootstrap)","Use context timeouts so queries fail fast on a dead server"],"tags":["go","database","query","dolt","sentinel-error"],"backgroundTag":"query-execution-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}