CLI flags silently overridden by config file for 13 parameters

[vividctrlalt]

Software Versions

Version : develop branch (commit 13b68eac0)

Expected behaviour

CLI flags should take priority over config file values. This is the standard convention (CLI > config file > default) and is already correctly implemented for 9 other parameters (e.g. --storage-db-directory, --trust-node) using the Optional pattern.

java -jar FullNode.jar --rpc-thread 16
# Expected: rpcThreadNum = 16

Actual behaviour

For 13 parameters, Args.setParam(Config) unconditionally overwrites the CLI value with the config file value. The CLI flags are silently ignored.

# config.conf contains: node.rpc.thread = 8
java -jar FullNode.jar --rpc-thread 16
# Actual: rpcThreadNum = 8 (CLI value lost)

Root cause — unconditional assignment in Args.setParam():

PARAMETER.rpcThreadNum = config.hasPath(ConfigKey.NODE_RPC_THREAD)
    ? config.getInt(ConfigKey.NODE_RPC_THREAD)
    : Runtime.getRuntime().availableProcessors() / 2;
// JCommander-set value of 16 is overwritten to 8

Frequency

100% — every time a config file key exists for any of the 13 affected parameters.

Steps to reproduce the behaviour

1. Set node.rpc.thread = 8 in config.conf
2. Start node with java -jar FullNode.jar -c config.conf --rpc-thread 16
3. Observe that rpcThreadNum is 8, not 16

Any of the following 13 parameters can reproduce the same issue:

#	CLI Flag	Field	Config Key
1	--support-constant	supportConstant	vm.supportConstant
2	--max-energy-limit-for-constant	maxEnergyLimitForConstant	vm.maxEnergyLimitForConstant
3	--lru-cache-size	lruCacheSize	vm.lruCacheSize
4	--min-time-ratio	minTimeRatio	vm.minTimeRatio
5	--max-time-ratio	maxTimeRatio	vm.maxTimeRatio
6	--long-running-time	longRunningTime	vm.longRunningTime
7	--save-internaltx	saveInternalTx	vm.saveInternalTx
8	--save-featured-internaltx	saveFeaturedInternalTx	vm.saveFeaturedInternalTx
9	--max-connect-number	maxHttpConnectNumber	node.maxHttpConnectNumber
10	--rpc-thread	rpcThreadNum	node.rpc.thread
11	--solidity-thread	solidityThreads	node.solidity.threads
12	--validate-sign-thread	validateSignThreadNum	node.validateSignThreadNum
13	--history-balance-lookup	historyBalanceLookup	storage.balance.history.lookup

Backtrace

Not applicable — no crash or exception. The bug is silent incorrect behavior.

---

Below is the full findings of all 34 @Parameter CLI flags in CommonParameter and additional findings.

full findings: all 34 CLI parameters by category

Category 1: Startup parameters (6) — No issue

Only control startup flow, no config file overlap.

CLI Flag	Field	Description
-c, --config	shellConfFileName	Config file path
-d, --output-directory	outputDirectory	Data directory
--log-config	logbackPath	Log config file
-h, --help	help	Print help and exit
-v, --version	version	Print version and exit
--password	password	Witness password

Category 2: CLI-only parameters (10) — No issue

Only set by CLI, setParam(Config) does not override.

CLI Flag	Field	Description
-w, --witness	witness	Witness mode
-p, --private-key	privateKey	Witness private key
--witness-address	witnessAddress	Witness address
--debug	debug	TVM debug mode
--fast-forward	fastForward	Fast forward mode
--solidity	solidityNode	Solidity node mode
--keystore-factory	keystoreFactory	KeystoreFactory mode
--p2p-disable	p2pDisable	Disable P2P module
--es	eventSubscribe	Enable event subscription
--contract-parse-enable	contractParseEnable	Contract parse switch

Category 3: CLI + Config, CLI priority (9) — Correct

Uses Optional pattern, CLI value takes priority when present.

CLI Flag	Field	Config Key
--storage-db-directory	storageDbDirectory	storage.db.directory
--storage-db-engine	storageDbEngine	storage.db.engine
--storage-db-synchronous	storageDbSynchronous	storage.db.synchronous
--storage-index-directory	storageIndexDirectory	storage.index.directory
--storage-index-switch	storageIndexSwitch	storage.index.switch
--storage-transactionHistory-switch	storageTransactionHistorySwitch	storage.transactionHistory.switch
--trust-node	trustNodeAddr	node.trustNode
--save-cancel-all-unfreeze-v2-details	saveCancelAllUnfreezeV2Details	vm.saveCancelAllUnfreezeV2Details
--seed-nodes	seedNodes	seed.node.ip.list

Category 4: CLI + Config, config overwrites CLI (13) — BUG

See "Steps to reproduce" section above for full list.

Other issues found during investigation

clearParam() misses 9 fields

clearParam() is used for test state reset, but the following fields are not cleared, which may cause test pollution:

• maxEnergyLimitForConstant, lruCacheSize
• allowDelegateOptimization, unfreezeDelayDays
• allowDynamicEnergy, dynamicEnergyThreshold, dynamicEnergyIncreaseFactor, dynamicEnergyMaxFactor
• saveCancelAllUnfreezeV2Details

Inconsistent default value patterns

Two patterns coexist in Args.setParam():

• Pattern A (ternary): default value explicit — config.hasPath(key) ? config.get(key) : defaultValue
• Pattern B (if-block, no else): default value hidden in CommonParameter field declaration

Mixing both increases maintenance burden. Suggest unifying to Pattern A.

CommonParameter overloaded

780 lines, ~150 fields, mixing CLI parameters, config file values, and runtime objects. Long-term suggestion: split into domain-specific classes (RpcConfig, StorageConfig, VmConfig, etc.).

Suggested improvement roadmap

Industry comparison

Project	CLI/Config Overlap	Strategy	Priority Rule
Nginx	Nearly none	CLI for startup ops only; all business config in file	CLI > config
Hadoop	Full overlap	All items overridable via -D key=value; multi-layer XML merge	CLI > site XML > default XML
Kubernetes	Heavy → deprecating CLI	Migrating to config file; CLI flags marked deprecated	CLI > config file

java-tron's current situation is most similar to early Kubernetes.

Short-term (current release): Fix the priority bug

if (PARAMETER.rpcThreadNum <= 0) {
    PARAMETER.rpcThreadNum = config.hasPath(ConfigKey.NODE_RPC_THREAD)
        ? config.getInt(ConfigKey.NODE_RPC_THREAD)
        : Runtime.getRuntime().availableProcessors() / 2;
}

Mid-term (next release): Deprecate overlapping CLI flags

@Deprecated  // Use node.rpc.thread in config.conf instead
@Parameter(names = {"--rpc-thread"}, description = "[DEPRECATED] Num of gRPC thread")
public int rpcThreadNum;

Long-term (future release): Converge to Nginx model

Only keep ~8 startup-class CLI parameters (-c, -d, -w, -p, -h, -v, --password, --log-config). All other runtime parameters managed exclusively by config file.

[waynercheung]

@vividctrlalt
Thank you for this thorough investigation!
We've verified the root cause in the codebase — setParam(Config) does indeed unconditionally overwrite JCommander-parsed CLI values for all 13 parameters, while 9 others correctly use the guard-check pattern.

This is a confirmed bug. We can discuss the fix approach below and have two questions before opening a PR.

Fix approach

Group 1 — Numeric parameters with zero-initialized defaults
(rpcThreadNum, solidityThreads, validateSignThreadNum, minTimeRatio)

These fields carry no explicit initializer (or are initialized to 0/0.0), so a <= 0 sentinel in setParam() is sufficient:

  // Example: rpcThreadNum
  if (PARAMETER.rpcThreadNum <= 0) {
      PARAMETER.rpcThreadNum = config.hasPath(Constant.NODE_RPC_THREAD)
          ? config.getInt(Constant.NODE_RPC_THREAD)
          : (Runtime.getRuntime().availableProcessors() + 1) / 2;
  }

Group 2 — Numeric parameters with non-zero defaults
(maxHttpConnectNumber = 50, longRunningTime = 10, lruCacheSize = 500, maxEnergyLimitForConstant = 100_000_000L, maxTimeRatio = calcMaxTimeRatio())

For these fields, a bare <= 0 guard would always be false against the field's initial value, silently breaking config loading entirely — worse than the current bug. The correct fix requires three coordinated changes:

1. Change the field initializer to a sentinel value (0 or -1.0) so that "CLI not provided" is reliably detectable.
2. Move the original default value into the setParam() fallback branch.
3. Update clearParam() to reset these fields to their sentinel values (not the runtime defaults), or the fix breaks in test environments.

  // CommonParameter.java
  public int    lruCacheSize              = 0;    // sentinel; was 500
  public int    longRunningTime           = 0;    // sentinel; was 10
  public int    maxHttpConnectNumber      = 0;    // sentinel; was 50
  public long   maxEnergyLimitForConstant = 0L;   // sentinel; was 100_000_000L
  public double maxTimeRatio              = -1.0; // sentinel; was calcMaxTimeRatio()

  // Args.java — sentinel guard, original default preserved in fallback
  if (PARAMETER.lruCacheSize <= 0) {
      PARAMETER.lruCacheSize = config.hasPath(Constant.VM_LRU_CACHE_SIZE)
          ? config.getInt(Constant.VM_LRU_CACHE_SIZE)
          : 500;
  }

  if (PARAMETER.maxTimeRatio < 0) {
      PARAMETER.maxTimeRatio = config.hasPath(Constant.VM_MAX_TIME_RATIO)
          ? config.getDouble(Constant.VM_MAX_TIME_RATIO)
          : calcMaxTimeRatio();
  }

Group 3 — Boolean flag parameters
(supportConstant, saveInternalTx, saveFeaturedInternalTx, historyBalanceLookup)

All four are declared with JCommander's default arity = 0. Under this model, there is no CLI syntax to explicitly pass false — the flag is either present (true) or absent (field retains its default false). Therefore false unambiguously means "CLI not provided", and a if (!PARAMETER.field) guard is the correct and complete fix with no loss of expressiveness:

  if (!PARAMETER.saveInternalTx && config.hasPath(Constant.VM_SAVE_INTERNAL_TX)) {
      PARAMETER.saveInternalTx = config.getBoolean(Constant.VM_SAVE_INTERNAL_TX);
  }

Upgrading to Boolean (nullable) + arity = 1 to support explicit --save-internaltx false would be a separate enhancement, out of scope for this fix.

Questions

1. Scope of PR: Should we address all 13 parameters in a single PR, or split them
   (e.g., Group 1 first as a low-risk change, Group 2 + Group 3 separately)?
2. clearParam() gaps: The Group 2 fix already updates clearParam() for maxEnergyLimitForConstant and lruCacheSize (resetting them to sentinel values).
   Should we also address the remaining 7 fields you identified as missing (allowDelegateOptimization, unfreezeDelayDays, allowDynamicEnergy, dynamicEnergyThreshold, dynamicEnergyIncreaseFactor, dynamicEnergyMaxFactor, saveCancelAllUnfreezeV2Details) in the same PR, or track them as a separate issue?

[waynercheung]

Great point — this is a legitimate operational concern worth addressing explicitly.

On the backward-compatibility risk

The affected population is users who simultaneously:

1. Pass one of the 13 CLI flags in their startup script, and
2. Have the same key in config.conf with a different value, and
3. Have unknowingly been relying on the (buggy) config-wins behavior

In practice this is a narrow set, since operators who discovered these CLI flags had no effect would have stopped using them. That said, the risk is real and deserves a mitigation.

Agreed: add an INFO-level log when CLI overrides config

We can log whenever a CLI-supplied value takes precedence over a config file value, making the override observable without requiring any config or log-level changes:

// Example for rpcThreadNum
if (PARAMETER.rpcThreadNum > 0) {
    if (config.hasPath(Constant.NODE_RPC_THREAD)
            && config.getInt(Constant.NODE_RPC_THREAD) != PARAMETER.rpcThreadNum) {
        logger.info("CLI flag --rpc-thread ({}) overrides config file value ({})",
            PARAMETER.rpcThreadNum, config.getInt(Constant.NODE_RPC_THREAD));
    }
} else {
    PARAMETER.rpcThreadNum = config.hasPath(Constant.NODE_RPC_THREAD)
        ? config.getInt(Constant.NODE_RPC_THREAD)
        : (Runtime.getRuntime().availableProcessors() + 1) / 2;
}

This pattern also applies to the 9 parameters that already work correctly today — consistent logging across all CLI-overridable parameters improves long-term observability.

Agreed: document as a behavior change in release notes

We can add an explicit entry such as:

Behavior change: CLI flags for 13 parameters now correctly take precedence over config file values (fixing a bug where config silently overwrote CLI).
Affected flags:

  --rpc-thread, --solidity-thread, --validate-sign-thread,
  --max-connect-number, --lru-cache-size, --long-running-time,
  --max-energy-limit-for-constant, --min-time-ratio, --max-time-ratio,
  --support-constant, --save-internaltx, --save-featured-internaltx,
  --history-balance-lookup

Action required for operators: review your startup scripts and verify that any of the above CLI flags reflect your intended configuration before upgrading.

Does this approach address your concern?