getsops/sops · error

missing scheme in Vault URL (should be like this: +https://v

Error message

missing scheme in Vault URL (should be like this: +https://vault.example.com:8200/v1/transit/keys/keyName), got: %v

What it means

NewMasterKeyFromURI parses a Vault key URI and requires a URL scheme such as https:// (hcvault/keysource.go:178). If the scheme is missing, the URI cannot be turned into a Vault address and this error is returned showing the original string.

Source

Thrown at hcvault/keysource.go:178

		}
		keys = append(keys, key)
	}
	return keys, nil
}

// NewMasterKeyFromURI obtains the Vault address, Transit backend path and the
// key name from the full URI of the key.
func NewMasterKeyFromURI(uri string) (*MasterKey, error) {
	var key *MasterKey
	if uri == "" {
		return key, nil
	}
	u, err := url.Parse(uri)
	if err != nil {
		return nil, err
	}
	if u.Scheme == "" {
		return nil, fmt.Errorf("missing scheme in Vault URL (should be like this: +"+
			"https://vault.example.com:8200/v1/transit/keys/keyName), got: %v", uri)
	}
	enginePath, keyName, err := engineAndKeyFromPath(u.RequestURI())
	if err != nil {
		return nil, err
	}
	u.Path = ""
	return NewMasterKey(u.String(), enginePath, keyName), nil

}

// NewMasterKey creates a new MasterKey from a Vault address, Transit backend
// path and a key name.
func NewMasterKey(address, enginePath, keyName string) *MasterKey {
	key := &MasterKey{
		VaultAddress: address,
		EnginePath:   enginePath,
		KeyName:      keyName,

View on GitHub (pinned to 13442bb981)

Solutions

1. Prefix the URI with the scheme, normally https:// (or http:// for plaintext dev Vault)
2. Check the hc_vault entries in .sops.yaml and any SOPS_HC_VAULT_* env values for missing schemes
3. If the value comes from a template/variable, ensure the scheme is part of the substituted value, not appended around it

Example fix

// before (.sops.yaml)
- hc_vault: vault.example.com:8200/v1/transit/keys/sops
// after
- hc_vault: https://vault.example.com:8200/v1/transit/keys/sops

// Go: ensure scheme before constructing the key
u, err := url.Parse(raw)
if err != nil || u.Scheme == "" {
    return nil, fmt.Errorf("vault URI %q must start with https://", raw)
}
key, err := hcvault.NewMasterKeyFromURI(raw)

func hasScheme(raw string) bool {
    u, err := url.Parse(raw)
    return err == nil && u.Scheme != ""
}

key, err := hcvault.NewMasterKeyFromURI(uri)
if err != nil && strings.Contains(err.Error(), "missing scheme in Vault URL") {
    return fmt.Errorf("prefix %q with https://", uri)
}

When it happens

Trigger: Calling NewMasterKeyFromURI / NewMasterKeysFromURIs (or sops parsing hc_vault entries in .sops.yaml / SOPS_VAULT_*) with a URI lacking 'https://' or 'http://', e.g. 'vault.example.com:8200/v1/transit/keys/keyname'.

Common situations: Writing the Vault address in .sops.yaml without the protocol prefix; stripping the scheme when templating configs; assuming the port suffix makes the scheme implicit.

Related errors

• %s's entry %d is empty
• could not parse %q into a valid Azure Key Vault MasterKey %v
• failed to construct Azure Key Vault client to decrypt data:
• config file not found
• invalid %s key configuration: expected string in list, got %

AI-assisted analysis of getsops/sops@13442bb981 (2026-09-01). Data as JSON: /api/errors/8d88fe0880d43ce3. Report an issue: GitHub.