cli: Return more helpful authentication errors

hodlinator commented at 9:43 am on March 31, 2026: contributor

Increases precision of error messages to help the user correct authentication issues.

Inspired by #34935.

DrahtBot added the label Scripts and tools on Mar 31, 2026

DrahtBot commented at 9:43 am on March 31, 2026: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	davidgumberg, maflcko, achow101
Concept ACK	janb84

If your review is incorrectly listed, please copy-paste <!–meta-tag:bot-skip–> into the comment that the bot should ignore.

Conflicts

Reviewers, this pull request conflicts with the following ones:

#34935 (cli: Return more correct error on -norpccookiefile without -rpcpassword by maflcko)
#34520 (refactor: Add [[nodiscard]] to functions returning bool+mutable ref by maflcko)
#31260 (scripted-diff: Type-safe settings retrieval by ryanofsky)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

maflcko commented at 9:49 am on March 31, 2026: member

AuthCookieResult::ERROR -> AuthCookieResult::ERR [The added Doxygen @retval AuthCookieResult::ERROR uses a non-existent enumerator name; the enum is ERR, so this would confuse readers about the intended return value.]

The LLM reminds me that ERROR (or any upper case name) may break when a windows (or other) header defines an ERROR macro, so I wonder if they can be changed to be CamelCase (Err, Ok, and Disabled).

refactor(rpc): GenerateAuthCookieResult -> AuthCookieResult

Type will be used for reading the cookie in next commit.

Also corrects ERR/ERROR mismatch in docstring in request.h, and changes to CamelCase to avoid potential collision with Windows headers (https://github.com/bitcoin/bitcoin/pull/34965#issuecomment-4161331392).

84c3f8d325

hodlinator force-pushed on Mar 31, 2026

DrahtBot added the label CI failed on Mar 31, 2026

cli: Clearer error messages on authentication failure

Co-authored-by: MarcoFalke <*~=`'#}+{/-|&$^_@721217.xyz>

20a94c1524

qa: Improve error message 257769a7ce

hodlinator force-pushed on Mar 31, 2026

hodlinator commented at 10:27 am on March 31, 2026: contributor

Changed to CamelCase as suggested by #34965 (comment). Also spelled out Error.

Fixed interface_ipc_cli.py failure too.

dookynme-bit commented at 10:32 am on March 31, 2026: none

Approve

dookynme-bit commented at 10:32 am on March 31, 2026: none

Approve

DrahtBot removed the label CI failed on Mar 31, 2026

in src/bitcoin-cli.cpp:953 in 257769a7ce

952+                break;
953+            case AuthCookieResult::Disabled:
954+                error += "Cookie file was disabled via -norpccookiefile and no rpcpassword was specified.";
955+                break;
956+            case AuthCookieResult::Ok:
957+                error += "Cookie file credentials were invalid and no rpcpassword was specified.";

janb84 commented at 3:38 pm on March 31, 2026:

0                error += "Cookie file does not contain valid credentials and no rpcpassword was specified.";

NIT: found this error message a bit hard to understand. In the original error msg, you could read it as “the credentials of the cookie file where not valid” Or without seeing the other error states, I can imagine that users mistake this error message for something is wrong with the file, not with the credentials in the file.

hodlinator commented at 9:37 am on April 7, 2026:

Minor, but I see what you mean. Might be more succinct to rephrase it as:

0                error += "Credentials within cookie file were invalid and no rpcpassword was specified.";

Sorry I didn’t get to this before the merge. Maybe it could be tacked on to a future PR.

in src/bitcoin-cli.cpp:959 in 257769a7ce

959+            }
960         } else {
961-            throw std::runtime_error("Authorization failed: Incorrect rpcuser or rpcpassword");
962+            error += "Incorrect rpcuser or rpcpassword were specified.";
963         }
964+        error += strprintf(" Configuration file: (%s)", fs::PathToString(gArgs.GetConfigFilePath()));

janb84 commented at 3:41 pm on March 31, 2026:

The config file path is now always included even when -rpcpassword was explicitly provided, is this intentional ?

0./bitcoin-cli -regtest -rpcpassword=test -getinfo
1error: Authorization failed: Incorrect rpcuser or rpcpassword were specified. Configuration file: (/Users/jan/Library/Application Support/Bitcoin/bitcoin.conf)

davidgumberg commented at 6:40 pm on April 1, 2026:

This seems reasonable, as it gives a hint to the user of where to look for the RPC authentication policy

hodlinator commented at 9:40 am on April 7, 2026:

I’m not aware of a way to detect the source of a setting (CLI/config file). Also, it could be that the -rpcpassword is correct, while the config file sets the wrong rpcuser. So I think the error message would still need to be somewhat ambiguous by nature.

janb84 commented at 3:45 pm on March 31, 2026: contributor

concept ACK 257769a7ce8c8ca70e705569f29aac244ada45aa

I like the more informative errors which will provide the end user a bit more insight what went wrong and what to do to correct the issue.

davidgumberg commented at 6:45 pm on April 1, 2026: contributor

utACK 257769a7ce8c8ca70e705569f29aac244ada45aa

DrahtBot requested review from janb84 on Apr 1, 2026

maflcko commented at 4:49 pm on April 2, 2026: member

review ACK 257769a7ce8c8ca70e705569f29aac244ada45aa 🦇

Signature:

0untrusted comment: signature from minisign secret key on empty file; verify via: minisign -Vm "${path_to_any_empty_file}" -P RWTRmVTMeKV5noAMqVlsMugDDCyyTSbA3Re5AkUrhvLVln0tSaFWglOw -x "${path_to_this_whole_four_line_signature_blob}"
1RUTRmVTMeKV5npGrKx1nqXCw5zeVHdtdYURB/KlyA/LMFgpNCs+SkW9a8N95d+U4AP1RJMi+krxU1A3Yux4bpwZNLvVBKy0wLgM=
2trusted comment: review ACK 257769a7ce8c8ca70e705569f29aac244ada45aa 🦇
3QZkHoQvw0ab68HadxYfVHq0HiobaSq24W88DFigSjBhGs6tXhAJvPRTo4LdcaR9SzdVeW9whADndhfmhBCzXBg==

achow101 commented at 10:49 pm on April 2, 2026: member

ACK 257769a7ce8c8ca70e705569f29aac244ada45aa

achow101 merged this on Apr 2, 2026

achow101 closed this on Apr 2, 2026

hodlinator commented at 9:49 am on April 7, 2026: contributor

Thanks for the review @janb84!

hodlinator deleted the branch on Apr 9, 2026

cli: Return more helpful authentication errors #34965

Reviews

Conflicts