glanceapp/glance · error

secret-key must be set when users are configured

Error message

secret-key must be set when users are configured

What it means

Validation requiring auth.secret-key when any users are configured under auth. Session tokens for HTTP basic/session auth are signed with this key; without it glance cannot securely authenticate the declared users.

Source

Thrown at internal/glance/config.go:457

		if debounceTimer != nil {
			debounceTimer.Stop()
		}

		return watcher.Close()
	}, nil
}

// TODO: Refactor, we currently validate in two different places, this being
// one of them, which doesn't modify the data and only checks for logical errors
// and then again when creating the application which does modify the data and do
// further validation. Would be better if validation was done in a single place.
func isConfigStateValid(config *config) error {
	if len(config.Pages) == 0 {
		return fmt.Errorf("no pages configured")
	}

	if len(config.Auth.Users) > 0 && config.Auth.SecretKey == "" {
		return fmt.Errorf("secret-key must be set when users are configured")
	}

	for username := range config.Auth.Users {
		if username == "" {
			return fmt.Errorf("user has no name")
		}

		if len(username) < 3 {
			return errors.New("usernames must be at least 3 characters")
		}

		user := config.Auth.Users[username]

		if user.Password == "" {
			if user.PasswordHashString == "" {
				return fmt.Errorf("user %s must have a password or a password-hash set", username)
			}
		} else if len(user.Password) < 6 {

View on GitHub (pinned to 91324e8de7)

Solutions

1. Add auth.secret-key with a long random string to glance.yml
2. If using variable expansion like ${SECRET_KEY}, verify the variable is actually set in the environment the process runs in
3. Generate a key with a password manager or openssl rand -base64 32 and store it outside the repo

Example fix

# before
auth:
  users:
    - username: alice
      password: hunter2
# after
auth:
  secret-key: ${GLANCE_SECRET_KEY}
  users:
    - username: alice
      password: ${GLANCE_USER_PASSWORD}

// Fail fast at startup with a clear message:
if len(cfg.Auth.Users) > 0 && os.Getenv("GLANCE_SECRET_KEY") == "" {
    log.Fatal("GLANCE_SECRET_KEY must be set when users are configured")
}

When it happens

Trigger: Config contains auth.users with at least one entry but auth.secret-key is empty/omitted. secret-key can also be supplied via environment/file variable expansion — the error means that expansion yielded nothing.

Common situations: Adding password protection from a tutorial but skipping the key line; setting secret-key via an env var (e.g. ${GLANCE_SECRET_KEY}) that is empty in the deployment environment; moving config to Docker and losing the env var.

Related errors

• user has no name
• user %s must have a password or a password-hash set
• the password for %s must be at least 6 characters
• %s widget: %v
• recursion depth limit of %d reached

AI-assisted analysis of glanceapp/glance@91324e8de7 (2026-08-15). Data as JSON: /api/errors/bf6f1bbe6fa94c18. Report an issue: GitHub.