{"record":{"id":"17bdc49ef226d69c","repo":"gastownhall/beads","slug":"list-remote-tracking-refs-w","errorCode":null,"errorMessage":"list remote-tracking refs: %w","messagePattern":"list remote-tracking refs: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/versioncontrolops/remoterefs.go","lineNumber":13,"sourceCode":"package versioncontrolops\n\nimport (\n\t\"context\"\n\t\"fmt\"\n)\n\n// ListRemoteRefs returns the names of all cached remote-tracking refs\n// (e.g. \"remotes/origin/main\"), sorted by name.\nfunc ListRemoteRefs(ctx context.Context, db DBConn) ([]string, error) {\n\trows, err := db.QueryContext(ctx, \"SELECT name FROM dolt_remote_branches ORDER BY name\")\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"list remote-tracking refs: %w\", err)\n\t}\n\tdefer rows.Close()\n\n\tvar refs []string\n\tfor rows.Next() {\n\t\tvar name string\n\t\tif err := rows.Scan(&name); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"scan remote-tracking ref: %w\", err)\n\t\t}\n\t\trefs = append(refs, name)\n\t}\n\treturn refs, rows.Err()\n}\n\n// PruneRemoteRefs deletes every cached remote-tracking ref and returns the\n// names deleted. After a history squash (Flatten/Compact) these refs still\n// anchor the pre-squash commit chain, so DOLT_GC treats the entire old history\n// as reachable and reclaims nothing (bd-agctw). Pruning is safe on a squashed","sourceCodeStart":1,"sourceCodeEnd":31,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/versioncontrolops/remoterefs.go#L1-L31","documentation":"ListRemoteRefs queries the dolt_remote_branches system table to enumerate cached remote-tracking refs (e.g. \"remotes/origin/main\"). This error wraps any failure of the initial QueryContext — typically a SQL error from the underlying Dolt database (missing system table, connection failure, server error, or cancelled context). It is thrown so callers can distinguish the listing step from later scan/delete failures.","triggerScenarios":"Calling ListRemoteRefs (directly or via PruneRemoteRefs) when db.QueryContext(ctx, \"SELECT name FROM dolt_remote_branches ORDER BY name\") fails: the connection is closed/broken, the Dolt server rejects the query, dolt_remote_branches is unavailable (very old Dolt version), or ctx is cancelled before the query starts.","commonSituations":"Database connection dropped mid-session; running against an embedded Dolt version that predates dolt_remote_branches; caller passed a context that was already cancelled or timed out; permissions/config issues preventing system-table reads.","solutions":["Check the wrapped error (%w) for the underlying cause: connection errors require reconnecting to the Dolt database before retrying.","If the context was cancelled/timed out, retry with a fresh, longer-lived context.","Verify the Dolt engine version supports dolt_remote_branches; upgrade the Dolt driver/server if the system table is missing.","Confirm the DBConn passed in is open and healthy (ping the database first)."],"exampleFix":"// before\nrefs, err := versioncontrolops.ListRemoteRefs(ctx, brokenConn)\n// after\nif err := db.PingContext(ctx); err != nil {\n    db, err = sql.Open(\"mysql\", dsn) // re-open stale connection\n}\nrefs, err := versioncontrolops.ListRemoteRefs(ctx, db)","handlingStrategy":"try-catch","validationCode":"if err := db.PingContext(ctx); err != nil {\n    return fmt.Errorf(\"database unavailable before ListRemoteRefs: %w\", err)\n}","typeGuard":"func isCtxCancelled(err error) bool {\n    return errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded)\n}","tryCatchPattern":"refs, err := versioncontrolops.ListRemoteRefs(ctx, db)\nif err != nil {\n    switch {\n    case errors.Is(err, context.Canceled), errors.Is(err, context.DeadlineExceeded):\n        // retry with fresh context\n    default:\n        return fmt.Errorf(\"listing remote refs failed: %w\", err)\n    }\n}","preventionTips":["Ping the database before running version-control operations.","Always pass a context with an adequate timeout for metadata queries.","Keep the Dolt driver/server version current so dolt_remote_branches exists.","Handle errors by unwrapping with errors.Is/errors.As to react to the root cause."],"tags":["dolt","sql","database"],"backgroundTag":"database-query-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}