hashicorp/nomad · error

Invalid key: %s

Error message

Invalid key: %s

What it means

initKeyring (command/agent/keyring.go:27) wraps the error from base64.StdEncoding.DecodeString when the --keyring-generate/--keyring or keyring key material supplied on the CLI is not valid standard base64. The agent aborts keyring-file creation with 'Invalid key: ...'. This is a startup/config failure: the key was provided but is malformed before any key-size validation happens.

Source

Thrown at command/agent/keyring.go:27

	"fmt"
	"os"
	"path/filepath"

	log "github.com/hashicorp/go-hclog"
	"github.com/hashicorp/memberlist"
	"github.com/hashicorp/serf/serf"
)

const (
	serfKeyring = "server/serf.keyring"
)

// initKeyring will create a keyring file at a given path.
func initKeyring(path, key string, l log.Logger) error {
	var keys []string

	if keyBytes, err := base64.StdEncoding.DecodeString(key); err != nil {
		return fmt.Errorf("Invalid key: %s", err)
	} else if err := memberlist.ValidateKey(keyBytes); err != nil {
		return fmt.Errorf("Invalid key: %s", err)
	}

	// Check for AES-256 key size (32-bytes)
	if len(key) < 32 {
		var encMethod string
		switch len(key) {
		case 16:
			encMethod = "AES-128"
		case 24:
			encMethod = "AES-192"
		}
		msg := fmt.Sprintf("given %d-byte gossip key enables %s encryption, generate a 32-byte key to enable AES-256", len(key), encMethod)
		l.Info(msg)
	}

	// Just exit if the file already exists.

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Base64-encode your key material with standard encoding (e.g. openssl rand -base64 32) before passing it.
2. Trim whitespace/newlines and shell-escaping artifacts from the key string.
3. Regenerate a fresh 32-byte key if the original cannot be recovered: openssl rand -base64 32.
4. If the key came from a URL-safe base64 source, re-encode it: base64.RawURLEncoding decode then base64.StdEncoding encode.

Example fix

// before
nomad agent -server -keyring-generate -keyring ./keyring -key 'my secret key with spaces'
// after
KEY=$(openssl rand -base64 32)
nomad agent -server -keyring-generate -keyring ./keyring -key "$KEY"

// Validate the keyring key before invoking nomad agent
keyBytes, err := base64.StdEncoding.DecodeString(key)
if err != nil {
    return fmt.Errorf("key must be standard base64: %w", err)
}
if err := memberlist.ValidateKey(keyBytes); err != nil {
    return fmt.Errorf("key invalid for memberlist: %w", err)
}

func isValidKeyringKey(key string) bool {
    b, err := base64.StdEncoding.DecodeString(strings.TrimSpace(key))
    return err == nil && memberlist.ValidateKey(b) == nil
}

if err := initKeyring(path, key, logger); err != nil {
    if strings.HasPrefix(err.Error(), "Invalid key:") {
        // regenerate a fresh base64 key and retry once
        key = generateKey()
        return initKeyring(path, key, logger)
    }
    return err
}

When it happens

Trigger: Running 'nomad agent ... -keyring-generate' or initKeyring with a key string containing characters outside the standard base64 alphabet (spaces, '!=', URL-safe '-_'), wrong padding, or a value that was quoted/escaped incorrectly in config.

Common situations: Copy-pasting a key with trailing whitespace or newline; using a URL-safe base64 key (with - and _) where standard encoding is required; forgetting to base64-encode a raw key at all; secrets managers stripping padding '='.

Related errors

• only one server.keyring can be active in Nomad Community Edi
• unknown keyring provider: %q
• unknown algorithm: %q
• no CNI network config found
• running container as ContainerAdmin is unsafe; change the co

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/863597168632abc6. Report an issue: GitHub.