--source, --output, --data-source-type and --metadata are…

Error message

--source, --output, --data-source-type and --metadata are not allowed when --ztdo-id is specified

What it means

The `nhp-device run --mode encrypt` command's Before hook rejects encrypt invocations that pass --ztdo-id together with --source, --output, --data-source-type or --metadata. Passing --ztdo-id means 'update an existing ZTDO', an operation that only takes the id plus required encrypt fields, so creation-time source options are treated as conflicting. The CLI surfaces this as a hard validation error before any work runs.

Solutions

Remove --source, --output, --metadata and --data-source-type from the command when --ztdo-id is given
If you meant to create a new ZTDO, drop --ztdo-id instead and keep the source options
If you meant to update, invoke with only --mode encrypt, --ztdo-id, --smart-policy and required decrypt-style fields

Example fix

// before
nhp-device run --mode encrypt --ztdo-id abc123 --source ./data.csv --output ./out.ztdo
// after
nhp-device run --mode encrypt --ztdo-id abc123 --smart-policy ./policy.wasm

Defensive patterns

Strategy: validation

Validate before calling

const updateOnly = ['source','output','metadata','data-source-type'];
if (flags['ztdo-id'] && updateOnly.some(f => flags[f])) {
  throw new Error('--ztdo-id is mutually exclusive with ' + updateOnly.join(', '));
}

Type guard

const isUpdateInvocation = (flags) => Boolean(flags['ztdo-id']);
const isCreateInvocation = (flags) => !flags['ztdo-id'];

Prevention

Build separate script wrappers for ZTDO create vs update
Never append --ztdo-id to an existing create command line
Lint CI scripts for the co-occurrence of --ztdo-id with source-side flags

When it happens

Trigger: Running `nhp-device run --mode encrypt --ztdo-id <id>` while also setting any of --source, --output, --metadata, or --data-source-type (non-empty string values).

Common situations: Copy-pasting a full create-ZTDO command line and appending --ztdo-id to 'reuse' an existing record; scripting that always passes --source/--output regardless of mode; forgetting that --data-source-type defaults are irrelevant when updating.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

AI-assisted analysis of OpenNHP/opennhp@6e04ca5ff0 (2026-09-07). Data as JSON: /api/errors/a7c5663f0d1af228. Report an issue: GitHub.

Appendix: source

Thrown at endpoints/db/main/main.go:59

			&cli.StringFlag{Name: "metadata", Value: "", Usage: "metadata file"},
			&cli.StringFlag{Name: "output", Value: "", Usage: "Save path of the ztdo file or decrypted file"},
			&cli.StringFlag{Name: "access-url", Value: "", Usage: "ZTDO access url for online or offline mode or API url for streaming mode"},
			&cli.StringFlag{Name: "ztdo", Value: "", Usage: "path to the ztdo file"},
			&cli.StringFlag{Name: "ztdo-id", Value: "", Usage: "identifier of the ztdo file"},
			&cli.StringFlag{Name: "data-private-key", Value: "", Usage: "data private key with base64 format"},
			&cli.StringFlag{Name: "provider-public-key", Value: "", Usage: "provider public key with base64 format"},
		},
		Before: func(c *cli.Context) error {
			if c.String("mode") == "encrypt" {
				if c.String("data-source-type") != "" {
					if !slices.Contains([]string{"online", "offline", "stream"}, c.String("data-source-type")) {
						return fmt.Errorf("invalid --data-source-type, allowed values are online, offline and stream")
					}
				}

				if c.String("ztdo-id") != "" { // update ztdo
					if c.String("source") != "" || c.String("output") != "" || c.String("metadata") != "" || c.String("data-source-type") != "" {
						return fmt.Errorf("--source, --output, --data-source-type and --metadata are not allowed when --ztdo-id is specified")
					}
				} else { // create ztdo
					if c.String("data-source-type") != "stream" {
						if c.String("source") == "" {
							return fmt.Errorf("--source is required when --data-source-type is not stream and --ztdo-id is not specified")
						}
					} else {
						if c.String("access-url") == "" {
							return fmt.Errorf("--access-url is required when --data-source-type is stream")
						}
					}
				}

				if c.String("smart-policy") == "" {
					return fmt.Errorf("--smart-policy is required in encrypt mode")
				}

				// only be available in decrypt mode

View on GitHub (pinned to 6e04ca5ff0)