Inconsistent behavior when overriding bitcoin.conf options from settings.json

vasild commented at 4:33 pm on February 26, 2024: contributor

Is there an existing issue for this?

I have searched the existing issues

Current behaviour

When bitcoind is started with the following configuration files:

settings.json:

0{
1    "listen": false
2}

bitcoin.conf:

0listen=1

Then it does not listen. This is expected. Options from settings.json override ones from bitcoin.conf. Both options co-exist in ArgsManager::m_settings::rw_settings (listen=0) and ArgsManager::m_settings::ro_config (listen=1). Then ArgsManager::GetBoolArg() selects the value from rw_settings.

Expected behaviour

What should be the behavior with the following?

settings.json:

0{
1    "listen": false
2}

bitcoin.conf:

0listenonion=1

I think that for consistency with the above, it should start and not listen. That is, listenonion=1 from bitcoin.conf should be overriden / set to 0. But instead bitcoind refuses to start:

0$ bitcoind
1Error: Cannot set -listen=0 together with -listenonion=1

Steps to reproduce

start bitcoin-qt, go to settings -> network and remove the checkbox from “Allow incoming connections”
shut down
add listenonion=1 in bitcoin.conf (might as well be done as first step)
start bitcoin-qt - it refuses to start with Error: Cannot set -listen=0 together with -listenonion=1

Relevant log output

No response

How did you obtain Bitcoin Core

Compiled from source

What version of Bitcoin Core are you using?

master@7143d4388407ab3d12005e55a02d5e8f334e4dc9

Operating system and version

any

Machine specifications

No response

vasild commented at 4:34 pm on February 26, 2024: contributor

First reported in https://github.com/bitcoin-core/gui/issues/567#issuecomment-1962422185

vasild commented at 4:40 pm on February 26, 2024: contributor

So, settings.json : listen=0 and bitcoin.conf : listenonion=1 is interpreted as bitcoind -listen=0 -listenonion=1 thus the rightful error. However settings.json : listen=0 and bitcoin.conf : listen=1 does not create a conflict even though, logically listen=0 vs listen=1 is even bigger conflict compared to listen=0 vs listenonion=1.

ryanofsky commented at 4:49 pm on February 26, 2024: contributor

I think the expected behavior you suggested above seems reasonable, that if -listen=0 and -listenonion=1 are specified the -listen=0 option takes precedence and incoming connections are not accepted. It would be nice to log or show a warning in this case.

I think current behavior of treating it like an error is also reasonable, too.

I’m not sure about about the new bug reported in https://github.com/bitcoin-core/gui/issues/567#issuecomment-1962422185 since it is i just a screenshot without steps to reproduce. If that bug is happening without anything specified on the command line or in bitcoin.conf like the original bug https://github.com/bitcoin-core/gui/issues/567 then that is a real unexpected problem and bug.

fanquake commented at 4:55 pm on February 26, 2024: member

When bitcoind is started with the following configuration files:

Can you add steps for how bitcoind can get into this state (without manually creating a settings.json, which we don’t support).

ryanofsky commented at 5:00 pm on February 26, 2024: contributor

However settings.json : listen=0 and bitcoin.conf : listen=1 does not create a conflict even though, logically listen=0 vs listen=1 is even bigger conflict compared to listen=0 vs listenonion=1.

settings.json is supposed to take precdence over bitcoin.conf. The idea is bitcoin.conf can have static values set by packager or os which are treated as defaults, and settings.json has dynamic values chosen by the user which override the defaults. But if user is both creating a bitcoin.conf and also changing settings.json through the gui or rpcs, settings.json will take precedence in that case too.

When bitcoind is started with the following configuration files:

Can you add steps for how bitcoind can get into this state (without manually creating a settings.json, which we don’t support).

It would be good to add steps to the description, but if you use the GUI and uncheck “allow in coming connections” in the gui network settings, “listen”: false will be added to settings.json.

vasild commented at 11:22 am on February 28, 2024: contributor

I’m not sure about about the new bug reported in https://github.com/bitcoin-core/gui/issues/567#issuecomment-1962422185 since it is i just a screenshot without steps to reproduce. If that bug is happening without anything specified on the command line or in bitcoin.conf like the original bug https://github.com/bitcoin-core/gui/issues/567 then that is a real unexpected problem and bug.

It requires listenonion=1 in bitcoin.conf.

Can you add steps for how bitcoind can get into this state

Added elaborate steps to reproduce in the PR description.

Is the solution here to set listen: false, listenonion: false in settings.json when “Allow incoming connections” is unchecked? Then any listenonion=1 from bitcoin.conf would be overriden as well, like any listen=1 is overriden now.

ryanofsky commented at 5:27 pm on February 28, 2024: contributor

Is the solution here to set listen: false, listenonion: false in settings.json when “Allow incoming connections” is unchecked?

I think that would be a good solution. Other solutions could be:

Adding the listenonion setting to the gui so it is visible (the proxy settings already have options for tor, so this would make the listening and proxy options more consistent)
Making the listen=0 listenonion=1 combination actually work by listening on only the localhost onion port only instead of allowing connections from anywhere.
Improving the current error message. If the user specified “listenonion=1” in the config file while also disabling connections it seems like a high chance that is unintentional. Probably it should just be a GUI warning, not a fatal error, though.

vasild commented at 1:47 pm on February 29, 2024: contributor

listen=0 listenonion=1 is not possible technically. Let me explain. The name listenonion= is really confusing and I got confused by it again. Maybe it is time to rename it. It has nothing to do with TCP listening (as in bind(2) and listen(2)). What listenonion= does is to connect to the Tor daemon and automatically create and configure a Tor service, like “Hey, Tor, please start listening on foobar.onion:8333 and redirect all connections to that to 127.0.0.1:8334”. It should be called autocreatetorservice=. Obviously, if we do not TCP listen on 127.0.0.1:8334 (controlled by listen=) then this cannot work.

It is further confusing because we can listen for onion connections even when listenonion=0 - if the Tor daemon is configured manually to redirect connections to foobar.onion:8333 to 127.0.0.1:8334 (where we run with bind=127.0.0.1:8334=onion which is the default).

Adding the listenonion setting to the gui so it is visible (the proxy settings already have options for tor, so this would make the listening and proxy options more consistent)

If this route is taken, then the GUI should only allow the following combinations: listen=0 listenonion=0 listen=1 listenonion=0 listen=1 listenonion=1

ryanofsky commented at 2:41 pm on February 29, 2024: contributor

I think that mostly makes sense, and definitely the most direct way to fix this issue would be one of the GUI fixes (making the Allow Incoming Connections checkbox disable both listen options, or improving the GUI error message and making it nonfatal, or adding a GUI option to control -listenonion).

And I agree the options are really confusing and poorly named. IMO we should deprecate -listen, -listenonion, -bind, -whitebind options while interpreting them for backwards compatibility, and design a new option that lets you directly specify what addresses, ports, and sockets you want to listen on using a general syntax like socat’s.

I just think, in theory, listen=0 listenonion=1 could do a sensible thing and disable listening in general while still autoconfiguring tor and listening exclusively on the localhost onion service port. Probably not worth the implementation complexity, but I don’t think it would be “not possible technically” unless I am missing something

willcl-ark added the label Settings on Oct 16, 2025

Inconsistent behavior when overriding bitcoin.conf options from settings.json #29482