{ "number": 30361, "repo": "bitcoin/bitcoin", "url": "https://github.com/bitcoin/bitcoin/pull/30361", "title": "doc: Drop description of LogError messages as fatal", "author": "ryanofsky", "author_association": "CONTRIBUTOR", "created_at": "2024-06-28T22:18:18Z", "updated_at": "2026-08-10T19:27:28Z", "age_days": 810, "draft": false, "labels": [ "Docs" ], "milestone": null, "base": "master", "head_sha": "5e2eb5bde2f08c8a55430d3cd4e4454f1180ebd4", "head_ref": "pr/nofat", "head_repo": "ryanofsky/bitcoin", "head_history": [ { "t": "2024-06-30T15:47:55Z", "sha": "b7aae361b273f2f439d3b278214b7e37908c8cb0" }, { "t": "2025-10-15T00:41:59Z", "sha": "5e2eb5bde2f08c8a55430d3cd4e4454f1180ebd4" } ], "additions": 5, "deletions": 6, "changed_files": 1, "commit_count": 1, "size_bucket": "S", "mergeable_state": "unknown", "bot": { "drahtbot": { "present": true, "reviews": { "concept_nack": [ { "login": "maflcko", "url": "https://github.com/bitcoin/bitcoin/pull/30361#issuecomment-2357864794" }, { "login": "ajtowns", "url": "https://github.com/bitcoin/bitcoin/pull/30361#issuecomment-3994811709" } ], "stale_ack": [ { "login": "l0rinc", "url": "https://github.com/bitcoin/bitcoin/pull/30361#issuecomment-2358369107" } ] }, "conflicts": [] } }, "acks_parsed": { "sedited": { "kind": "ack", "hash": "5e2eb5bde2f08c8a55430d3cd4e4454f1180ebd4", "t": "2026-03-02T10:16:10Z", "stale": false }, "ajtowns": { "kind": "concept_nack", "hash": null, "t": "2026-03-04T02:19:38Z", "stale": false } }, "acks_tally": { "ack": 1, "stale_ack": 0, "concept_ack": 0, "approach_ack": 0, "nack": 0, "concept_nack": 1, "approach_nack": 0 }, "reviews": { "approved": 2, "changes_requested": 0, "distinct_reviewers": [ "ajtowns", "l0rinc", "maflcko", "sedited" ] }, "signals": { "needs_rebase": false, "ci_failed": false, "mergeable_state": "unknown", "last_author_activity": "2025-10-15T00:41:59Z", "last_reviewer_activity": "2026-08-10T19:27:23Z", "last_reviewer": "sedited", "author_silent_days": 337, "waiting_on_author_days": 37, "days_since_update": 37 }, "refs": { "mentioned": [ 24464, 29236, 30347, 30348, 30364, 34729, 34730 ], "depends_on": [], "fixes": [ 30348 ], "linked_issues": [ { "number": 30348, "type": "issue", "state": "open", "merged": false, "merged_at": null, "title": "RFC: Misused LogError and LogWarning macros" } ], "references": [ { "number": 30348, "type": "issue", "state": "open", "merged": false, "merged_at": null, "title": "RFC: Misused LogError and LogWarning macros" }, { "number": 30347, "type": "pull", "state": "closed", "merged": false, "merged_at": null, "title": "logging: Use LogFatal instead LogError for fatal errors" }, { "number": 24464, "type": "pull", "state": "closed", "merged": true, "merged_at": "2022-05-24", "title": "logging: Add severity level to logs" }, { "number": 29236, "type": "pull", "state": "closed", "merged": true, "merged_at": "2024-03-12", "title": "log: Nuke error(...)" }, { "number": 30364, "type": "pull", "state": "closed", "merged": false, "merged_at": null, "title": "logging: Replace LogError and LogWarning with LogAlert" }, { "number": 34729, "type": "pull", "state": "open", "merged": false, "merged_at": null, "title": "Reduce log noise" }, { "number": 34730, "type": "pull", "state": "open", "merged": false, "merged_at": null, "title": "util/log: Combine the warning/error log levels into a single alert level" } ], "conflicts": [] }, "stack": { "shares_commits_with": [], "based_on": [], "base_for": [] }, "review_paths": [ "doc/developer-notes.md" ], "body": "Remove documentation that says `LogError` should be used for \"severe problems that require the node (or a subsystem) to shut down entirely\" because:\n\n- It is not how `LogError` and `Level::Error` are used currently. Of 129 current uses only 58 cases are fatal according to [#30348](https://github.com/bitcoin/bitcoin/issues/30348)\n\n- \"[T]here's not much benefit in a log that says \"hey this error is about to cause the node to stop\" -- you already get that information by seeing \"Shutdown: in progress...\" immediately following.\" according to [#30347 (comment)](https://github.com/bitcoin/bitcoin/pull/30347#discussion_r1659096893)\n\nFixes #30348", "commits": [ { "sha": "5e2eb5bde2f08c8a55430d3cd4e4454f1180ebd4", "date": "2025-10-10T19:52:00Z", "message": "doc: Drop description of LogError messages as fatal\n\nRemove documentation that says LogError should be used for \"severe problems\nthat require the node (or a subsystem) to shut down entirely\" because:\n\n- This is not how `LogError` and `Level::Error` are used currently. Of 129\n current uses only 58 cases are fatal according to\n https://github.com/bitcoin/bitcoin/issues/30348\n\n- \"[T]here's not much benefit in a log that says \"hey this error is about to\n cause the node to stop\" -- you already get that information by seeing\n \"Shutdown: in progress...\" immediately following.\" according to\n https://github.com/bitcoin/bitcoin/pull/30347#discussion_r1659096893" } ], "timeline": [ { "t": "2024-06-28T23:58:50Z", "kind": "comment", "who": "ajtowns", "assoc": "CONTRIBUTOR", "text": "I think both entries should continue to include examples.\n\nI think removing \"severe\" from the LogWarning description doesn't make sense -- anything the admin might have to address is a severe (potential) problem, isn't it?\n\nHaving LogError mean \"the node admin **will** need to address\" vs LogWarning mean \"the node admin **may** need to address\" seems to argue towards retaining the \"LogError is fatal\" interpretation to me -- fatal errors are ones the admin does need address; anything else they can ignore until it becomes fatal.\n\nA potential advantage of having LogError (or LogFatal) reserved for fatal errors is that you could grep through the codebase for LogError to see all the potentially fatal errors, and perhaps work on finding ways to make them less fatal. Not convinced that's very beneficial though.\n\nI don't think there's much other benefit to splitting potential problems up from actual problems otherwise if the admin still needs to attend to them either way, though; so if we're already making LogError just mean actual errors; is there any reason not to merge them both into a single LogAlert() or similar?" }, { "t": "2024-06-30T15:47:55Z", "kind": "force_push", "who": "ryanofsky", "commit": "b7aae361b273f2f439d3b278214b7e37908c8cb0" }, { "t": "2024-06-30T15:55:57Z", "kind": "comment", "who": "ryanofsky", "assoc": "CONTRIBUTOR", "text": "re: https://github.com/bitcoin/bitcoin/pull/30361#issuecomment-2197781492\n\nThanks, added back examples and \"severe\".\n\nI think probably just looking at AbortNode callers would be as effective as as searching for fatal error messages, if looking for places to make error handling more robust.\n\nI do like the alert level idea and posted an implementation in #30364.\n\nUpdated 5175cbcbb00d6212cf548de428f43cb0c2a1be4b -> b7aae361b273f2f439d3b278214b7e37908c8cb0 ([`pr/nofat.1`](https://github.com/ryanofsky/bitcoin/commits/pr/nofat.1) -> [`pr/nofat.2`](https://github.com/ryanofsky/bitcoin/commits/pr/nofat.2), [compare](https://github.com/ryanofsky/bitcoin/compare/pr/nofat.1..pr/nofat.2)) with clarifications and examples.\n\nRebased b7aae361b273f2f439d3b278214b7e37908c8cb0 -> 5e2eb5bde2f08c8a55430d3cd4e4454f1180ebd4 ([`pr/nofat.2`](https://github.com/ryanofsky/bitcoin/commits/pr/nofat.2) -> [`pr/nofat.3`](https://github.com/ryanofsky/bitcoin/commits/pr/nofat.3), [compare](https://github.com/ryanofsky/bitcoin/compare/pr/nofat.2-rebase..pr/nofat.3))" }, { "t": "2024-07-16T20:12:54Z", "kind": "comment", "who": "maflcko", "assoc": "MEMBER", "text": "[quoted text omitted]\n\nThe reason is that many stem from `error()`, see also https://github.com/bitcoin/bitcoin/pull/30364#pullrequestreview-2181072864.\n\n[quoted text omitted]\nAgree, but then just go with #30364? Seems odd to change something twice, when it can be changed once?\n\nweak NACK for now." }, { "t": "2024-08-16T21:58:29Z", "kind": "comment", "who": "ryanofsky", "assoc": "CONTRIBUTOR", "text": "re: https://github.com/bitcoin/bitcoin/pull/30361#issuecomment-2231748835\n\nI think I might not have enough information to understand the weak nack, because I don't actually see a reason in there to reject a documentation fix that is only dropping advice to interpret `Error` as \"fatal\" and `Warning` as \"nonfatal\".\n\nThe advice is not followed by current code, but more importantly, I don't think anybody (even the original author) currently thinks this advice is something we should try to implement anymore. If something in this PR makes the documentation worse, it'd be helpful to know where the problems are. Otherwise this seems like a clean fix for the issue described in #30348, and a way to close that issue and move on to other fixes and improvements.\n\nI do understand what you are saying about the `error()` removal in #29236 making the issue described in #30348 worse because it increased the amount of Error spam. But it's not like this PR is changing documentation to say that Error spam is ok. It is clearly not. It is just trying to remove a separate point of confusion." }, { "t": "2024-08-27T07:18:20Z", "kind": "comment", "who": "maflcko", "assoc": "MEMBER", "text": "[quoted text omitted]\n\nIt is the line prior: \"Seems odd to change something twice, when it can be changed once? weak NACK for now.\"\n\nNow that the other pull is closed, I guess this is fine." }, { "t": "2024-08-27T07:23:35Z", "kind": "comment", "who": "maflcko", "assoc": "MEMBER", "text": "lgtm ack b7aae361b273f2f439d3b278214b7e37908c8cb0\n\nSeems fine to change the documentation here to be a description of what the code does right now. Also, it seems fine for this description to be applied going forward, because both an \"Error\" or \"Warning\" should be considered an Alert for the node admin to investigate (and possibly dismiss) (with or without the node shutting down).\n\nThere are probably cases where an Error can be \"downgraded\" to a Warning in the code, but they can be done in follow-up changes." }, { "t": "2024-08-27T09:22:45Z", "kind": "comment", "who": "ajtowns", "assoc": "CONTRIBUTOR", "text": "[quoted text omitted]\n\nPresuming that if it's me who's he-who-must-not-be-named here rather than referring back to #24464 etc, what I think is that if we're going to have distinct log levels for \"error\" and \"warning\", I think there should be a clear documented difference between what they are, so that PR authors, reviewers and users can know what to expect. If there's places in our code that don't meet that expectation, then that's something that should be fixed, though it doesn't need to be treated as some huge priority. On the other hand, if there's no distinction between the levels that's worth making, we shouldn't have two levels. So I think either the status quo or #30364 is better than this PR. It's not really worth arguing about, but it's frustrating having people put words in my mouth that aren't mine." }, { "t": "2024-09-18T08:45:14Z", "kind": "comment", "who": "maflcko", "assoc": "MEMBER", "text": "[quoted text omitted]\n\nI tend to agree on a second thought. This pull just seems to increase the long-term confusion by treating the levels equivalent or similar, just because some parts of the code happen to confuse them (for various reasons).\n\nAlso, as pointed out in https://github.com/bitcoin/bitcoin/pull/30364#discussion_r1711345479 (and other comments) a good chunk of the log statements that this doc-only pull is trying to \"fix\" shouldn't be log statements at all.\n\nSo overall I am NACK -ish on increasing confusion in the docs, motivated by code that will be removed or changed long-term anyway." }, { "t": "2024-09-18T12:34:38Z", "kind": "review_comment", "who": "l0rinc", "assoc": "CONTRIBUTOR", "path": "doc/developer-notes.md", "commit": "b7aae361b273f2f439d3b278214b7e37908c8cb0", "in_reply_to": null, "text": "nit: *`instead of`* seems [slightly more common](https://www.italki.com/en/post/question-107941) than *`in place of`* + `that` to streamline readability + `needs to address` to imply urgency:\n```suggestion\n- `LogError(fmt, params...)` should be used instead of `LogInfo` for severe errors\n that the node admin needs to address (e.g., failure to write data).\n```" }, { "t": "2024-09-18T12:42:40Z", "kind": "review_comment", "who": "l0rinc", "assoc": "CONTRIBUTOR", "path": "doc/developer-notes.md", "commit": "5e2eb5bde2f08c8a55430d3cd4e4454f1180ebd4", "in_reply_to": null, "text": "nit: the logger order is weird, why debug -> info -> error -> warning -> trace?\nEspecially after announcing `LogInfo`, `LogDebug`, `LogTrace`, `LogWarning` and `LogError` in the intro." }, { "t": "2024-09-18T12:43:23Z", "kind": "comment", "who": "l0rinc", "assoc": "CONTRIBUTOR", "text": "While I understand why @maflcko doesn't want to change twice, this seems to me like a slight improvement.\n\nutACK b7aae361b273f2f439d3b278214b7e37908c8cb0" }, { "t": "2024-09-18T12:43:45Z", "kind": "review", "who": "l0rinc", "assoc": "CONTRIBUTOR", "state": "APPROVED", "commit": "b7aae361b273f2f439d3b278214b7e37908c8cb0", "text": "" }, { "t": "2025-10-15T00:41:59Z", "kind": "force_push", "who": "ryanofsky", "commit": "5e2eb5bde2f08c8a55430d3cd4e4454f1180ebd4" }, { "t": "2026-03-02T10:16:10Z", "kind": "review", "who": "sedited", "assoc": "CONTRIBUTOR", "state": "APPROVED", "commit": "5e2eb5bde2f08c8a55430d3cd4e4454f1180ebd4", "text": "ACK 5e2eb5bde2f08c8a55430d3cd4e4454f1180ebd4" }, { "t": "2026-03-02T10:27:36Z", "kind": "review_comment", "who": "maflcko", "assoc": "MEMBER", "path": "doc/developer-notes.md", "commit": "5e2eb5bde2f08c8a55430d3cd4e4454f1180ebd4", "in_reply_to": null, "text": "Still not sure about this. Would it not be more consistent to downgrade a harmless write failure to a warning?" }, { "t": "2026-03-02T10:30:46Z", "kind": "review", "who": "maflcko", "assoc": "MEMBER", "state": "COMMENTED", "commit": "5e2eb5bde2f08c8a55430d3cd4e4454f1180ebd4", "text": "I am still not sure about this. I understand that the distinction is not clear in the code, but I think the docs can serve as a guide to what the \"final\" code should look like. I don't think we should \"weaken\" the docs, just because the current code isn't ideal.\nThe fist section of the dev notes also explain this process:\n\n```md\n## Coding Style (General)\n\nVarious coding styles have been used during the history of the codebase,\nand the result is not very consistent. However, we're now trying to converge to\na single style, which is specified below. When writing patches, favor the new\nstyle over attempting to mimic the surrounding style, except for move-only\ncommits.\n\n```\n\nAlso, this is sold as a fix for https://github.com/bitcoin/bitcoin/issues/30348, but most of the points in there seem to be outdated/stale?" }, { "t": "2026-03-02T10:45:15Z", "kind": "comment", "who": "sedited", "assoc": "CONTRIBUTOR", "text": "[quoted text omitted]\n\nThe text proposed now does read more correct to me. I'm not sure if all the exceptions to the \"error <=> fatal\" equivalence should eventually be changed." }, { "t": "2026-03-02T11:05:42Z", "kind": "comment", "who": "maflcko", "assoc": "MEMBER", "text": "[quoted text omitted]\n\nI think it is hard to make general calls without also looking at representative examples. Also, if there are specific modules that should be exempt, it could make sense to adjust the dev notes for them, so that it is more obvious where to break the rule, and if it makes sense to break the rule at all, or if there is a better third alternative possible.\n\nFor example, if the point is that (let's say) an index write io error should not lead to a crash, then that seems reasonable. However, just logging and continuing normally (hiding the error log in the scrollback) doesn't seem ideal either. Whether that log is a warning or error may not matter much at all? Possibly it is better to disconnect the index, so that no stale results are silently returned?" }, { "t": "2026-03-03T20:08:24Z", "kind": "comment", "who": "sedited", "assoc": "CONTRIBUTOR", "text": "[quoted text omitted]\n\nAnother example are a few of the validation failures. For example we don't shutdown in all cases where a block read from disk subsequently fails `CheckBlock()`. This should require intervention, since it should be highly unusual for a node to let a bad block in in the first place. A warning might be more appropriate there too, but I think a log level providing distinction between severe and minor issues makes sense for things like these." }, { "t": "2026-03-04T02:19:38Z", "kind": "comment", "who": "ajtowns", "assoc": "CONTRIBUTOR", "text": "Concept NACK.\n\nMost of the issues here -- that is, where not-very-important errors are logged via `LogError` -- were introduced via scripted-diff in #29236 without putting much thought into whether the old `error()` and the then-new `LogError` were a good match. This change just retroactively makes that PR's acks be in line with the docs.\n\nBut logging not-very-important errors as `LogError` (or even `LogWarning`) is not a desirable thing for our codebase; the entire value of tagging some log messages as warning/error is that it's important for them to be acted upon.\n\nI don't think this set of issues and PRs (#30347, #30348, #30361, #30364) has achieved anything except to serve as an ongoing distraction from improving those log messages." }, { "t": "2026-03-04T06:40:05Z", "kind": "comment", "who": "maflcko", "assoc": "MEMBER", "text": "[quoted text omitted]\n\nDoes it? Realistically, I presume this can happen either because you are a buggy miner, or a random p2p node happened to be connected to a buggy miner. I haven't checked if the invalid block 809478 incident triggers this log, but if it did, a normal user would not be required to intervene. The miner itself certainly should intervene (in their own interest), but I don't think this will happen via debug log parsing. Hopefully, they are checking the RPC block submit result (or IPC mining block submit result) for errors." }, { "t": "2026-03-04T12:56:30Z", "kind": "comment", "who": "ajtowns", "assoc": "CONTRIBUTOR", "text": "#34730 is an alternative to this for the long term, removing the distinction between error/warning levels; #34729 fixes up the incorrect log levels that wouldn't be fixed by merging error/warning." }, { "t": "2026-05-10T11:28:43Z", "kind": "comment", "who": "sedited", "assoc": "CONTRIBUTOR", "text": "Retracting my A-C-K here. Seems like we were closer to realizing the log level guidelines than I thought. Given the two standing N-A-C-Ks, I think this should be closed." }, { "t": "2026-08-10T19:27:23Z", "kind": "comment", "who": "sedited", "assoc": "CONTRIBUTOR", "text": "@ryanofsky what is your intent here? As this stands, it has 3 NACKs." } ], "labels_log": [ { "t": "2024-06-28T22:18:23Z", "action": "labeled", "label": "Docs", "who": "DrahtBot" }, { "t": "2025-03-17T08:37:07Z", "action": "labeled", "label": "CI failed", "who": "DrahtBot" }, { "t": "2025-07-24T13:03:55Z", "action": "labeled", "label": "Needs rebase", "who": "DrahtBot" }, { "t": "2025-09-26T12:00:39Z", "action": "unlabeled", "label": "CI failed", "who": "maflcko" }, { "t": "2025-10-15T00:56:44Z", "action": "unlabeled", "label": "Needs rebase", "who": "DrahtBot" } ], "state_log": [ { "t": "2024-06-30T15:56:21Z", "kind": "ready_for_review", "who": "ryanofsky" } ], "text_chars": 11887, "text_tokens_estimate": 2971, "changed_paths": [ "doc/developer-notes.md" ], "files": [ { "path": "doc/developer-notes.md", "add": 5, "del": 6 } ], "test_lines": 0, "git": { "head": "5e2eb5bde2f08c8a55430d3cd4e4454f1180ebd4", "head_matches_backup": true, "base": "d2987102dd13f965c7a0bf1d5b8ee15bcf025398", "commits": [ { "sha": "5e2eb5bde2", "subject": "doc: Drop description of LogError messages as fatal", "files": 1, "add": 5, "del": 6 } ], "patch_truncated": false }, "input_hash": "786c99a9d6feccbe", "extracted_at": "2026-09-17T16:15:31+00:00" }