cli: Return more helpful authentication errors #34965

pull hodlinator wants to merge 3 commits into bitcoin:master from hodlinator:pr/34935_suggestions changing 7 files +61 −48

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 <code></code> 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).

Type	Reviewers
ACK	davidgumberg, maflcko, achow101
Concept ACK	janb84

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:

                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:

                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 ?

./bitcoin-cli -regtest -rpcpassword=test -getinfo error: 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 🦇

<details><summary>Show signature</summary>

Signature:

untrusted 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}"
RUTRmVTMeKV5npGrKx1nqXCw5zeVHdtdYURB/KlyA/LMFgpNCs+SkW9a8N95d+U4AP1RJMi+krxU1A3Yux4bpwZNLvVBKy0wLgM=
trusted comment: review ACK 257769a7ce8c8ca70e705569f29aac244ada45aa 🦇
QZkHoQvw0ab68HadxYfVHq0HiobaSq24W88DFigSjBhGs6tXhAJvPRTo4LdcaR9SzdVeW9whADndhfmhBCzXBg==

</details>

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

Contributors

Review Requested
janb84

Labels

Scripts and tools

Linked (view graph)

#34935 cli: Return more correct error on -norpccookiefile without -rpcpassword

cli: Return more helpful authentication errors #34965

Reviews

Conflicts