Refine dmctl error messages for "secret key is not initialized "

[Frank945946]

What did you do?

Since v8.0, the hardcoded secret key for dmctl has been removed. As a result, when customers want to use dmctl to encrypt and decrypt the passwords of the source and target databases in the DM task configuration files, they need to upload the secret key to the DM Master and set the secret-key-path parameter in the DM Master configuration file. Otherwise, an error will be returned:

[root@svr1 ~]# tiup dmctl encrypt 'abc!@#123' --master-addr [192.168.0.2:8261](http://192.168.0.2:8261/)
Starting component dmctl: /root/.tiup/components/dmctl/v8.1.0/dmctl/dmctl encrypt abc!@#123 --master-addr [192.168.0.2:8261](http://192.168.0.2:8261/)
Error: secret key is not initialized 

The error message is unhelpful, as users do not know how to resolve the issue.

What did you expect to see?

Refine the error message to help users resolve the issue easily on their own.
For example:
Error: The secret key for dmctl has not been initialized. Please ensure that the required key has been uploaded to the DM Master node and that the secret-key-path parameter in the DM Master configuration file is set to its path on the DM Master.

What did you see instead?

Error: secret key is not initialized

Versions of the cluster

v8.1 and v8.5

(paste DM version here, and you must ensure versions of dmctl, DM-worker and DM-master are same)

Upstream MySQL/MariaDB server version:

(paste upstream MySQL/MariaDB server version here)

Downstream TiDB cluster version (execute SELECT tidb_version(); in a MySQL client):

(paste TiDB cluster version here)

How did you deploy DM: tiup or manually?

(leave TiUP or manually here)

Other interesting information (system version, hardware config, etc):

>
>

current status of DM cluster (execute query-status <task-name> in dmctl)

(paste current status of DM cluster here)

[alastori]

Hi @Frank945946,

Thanks for submitting this issue and for the initial proposed improvement:

Earlier Proposal:
"Error: The secret key for dmctl has not been initialized. Please ensure that the required key has been uploaded to the DM Master node and that the secret-key-path parameter in the DM Master configuration file is set to its path on the DM Master."

This is a good improvement over the original message, but I believe we can refine it further to improve clarity, readability, and make it more actionable.

Suggested Refinement

To make the message more structured and easier to follow, I suggest the following format:

Error: Secret key not initialized. 
To enable encryption:
1. Create a file containing a 32-byte (64-character) hexadecimal AES-256 secret key.
2. Set `secret-key-path` in DM-master’s configuration file to point to this key file.
3. Restart DM-master to apply the configuration.
For details, see: https://docs.pingcap.com/tidb/stable/dm-customized-secret-key

Why This Change?

• Many CLI tools, such as AWS CLI, Terraform, and Microsoft CLI, follow a user-actionable and structured error message approach
• Message should tell the user what is required as a fix, rather than only complaining that there is an error
• The numbered format makes it easier for users to scan and follow.
• Instead of just describing the issue, it provides specific steps to resolve it.
• Users don’t need to infer next steps from a single sentence.
• I see in errors.toml we already reference URLs.

Let me know your thoughts. Does this revision make sense?

Best,
@alastori

[Frank945946]

@alastori LGTM