syncthing/syncthing · error

Both --gui-address and --gui-apikey should be specified

Error message

Both --gui-address and --gui-apikey should be specified

What it means

Thrown by the syncthing CLI's api client factory when exactly one of --gui-address / --gui-apikey is set on the command line. The contract is all-or-nothing: either you give both (remote instance) or neither (values are pulled from the local config.xml). One-sided flags are rejected before any HTTP call.

Source

Thrown at cmd/syncthing/cli/client.go:54

	cfg    config.GUIConfiguration
	apikey string
}

type apiClientFactory struct {
	cfg config.GUIConfiguration
}

func (f *apiClientFactory) getClient() (APIClient, error) {
	// Now if the API key and address is not provided (we are not connecting to a remote instance),
	// try to rip it out of the config.
	if f.cfg.RawAddress == "" && f.cfg.APIKey == "" {
		var err error
		f.cfg, err = loadGUIConfig()
		if err != nil {
			return nil, err
		}
	} else if f.cfg.Address() == "" || f.cfg.APIKey == "" {
		return nil, errors.New("Both --gui-address and --gui-apikey should be specified")
	}

	httpClient := http.Client{
		Transport: &http.Transport{
			TLSClientConfig: &tls.Config{
				InsecureSkipVerify: true,
			},
			DialContext: func(_ context.Context, _, _ string) (net.Conn, error) {
				return net.Dial(f.cfg.Network(), f.cfg.Address())
			},
		},
	}
	return &apiClient{
		Client: httpClient,
		cfg:    f.cfg,
		apikey: f.cfg.APIKey,
	}, nil
}

View on GitHub (pinned to 058bcd7334)

Solutions

1. Provide both flags together: --gui-address <addr> --gui-apikey <key>
2. Or drop both flags so the CLI reads GUI address/API key from the local config.xml
3. Copy the API key from the GUI (Actions > API Key) or <apikey> in config.xml

Example fix

# before
syncthing cli show system --gui-address http://127.0.0.1:8384
# error: Both --gui-address and --gui-apikey should be specified

# after
syncthing cli show system --gui-address http://127.0.0.1:8384 --gui-apikey abc123

// before calling getClient / running the CLI
if (guiAddress != "") != (guiAPIKey != "") {
    return errors.New("pass both --gui-address and --gui-apikey, or neither")
}

When it happens

Trigger: Running e.g. 'syncthing cli show system --gui-address 127.0.0.1:8384' without --gui-apikey, or passing only --gui-apikey. Any 'syncthing cli ...' subcommand that builds an API client hits this.

Common situations: Users assume the address alone suffices because the GUI has no auth locally; scripts migrated from older CLI versions that accepted a single flag; copy-pasted examples with the key redacted.

Related errors

• could not find GUI Address
• could not find GUI API key
• {HTTP response body}
• either both or none of --config and --data must be given, us
• --home must not be used together with --config and --data

AI-assisted analysis of syncthing/syncthing@058bcd7334 (2026-08-15). Data as JSON: /api/errors/e63cd2156d4d456f. Report an issue: GitHub.