k3s-io/k3s · error

server token not found

Error message

server token not found

What it means

tokenRotate in pkg/server/handlers/token.go reads the server's passwd file (control.Runtime.PasswdFile, by default /var/lib/rancher/k3s/server/cred/passwd) and looks up the entry named 'server'. If no 'server' user exists in that file, rotation aborts with 'server token not found' because there is no current token to swap.

Source

Thrown at pkg/server/handlers/token.go:76

		return nil
	}

	token, err := clientaccess.FormatToken(token, certs)
	if err != nil {
		return err
	}
	return os.WriteFile(file, []byte(token+"\n"), 0600)
}

func tokenRotate(ctx context.Context, control *config.Control, newToken string) error {
	passwd, err := passwd.Read(control.Runtime.PasswdFile)
	if err != nil {
		return err
	}

	oldToken, found := passwd.Pass("server")
	if !found {
		return errors.New("server token not found")
	}
	if newToken == "" {
		newToken, err = util.Random(16)
		if err != nil {
			return err
		}
	}

	if newToken, err = util.NormalizeToken(newToken); err != nil {
		return err
	}

	if err := passwd.EnsureUser("server", version.Program+":server", newToken); err != nil {
		return err
	}

	// If the agent token is the same a server, we need to change both
	if agentToken, found := passwd.Pass("node"); found && agentToken == oldToken && control.AgentToken == "" {

View on GitHub (pinned to 6ba341e396)

Solutions

1. Inspect the file: grep '^server:' /var/lib/rancher/k3s/server/cred/passwd - it must contain the server entry (format: 'server:<token>,<groups>').
2. Restore the passwd file from a backup of /var/lib/rancher/k3s/server/cred/.
3. If no backup exists, restore from a snapshot or etcd backup of the node's credentials rather than hand-crafting tokens.
4. After the file is intact, retry 'k3s token rotate'.

# Before rotating, confirm the server entry exists
grep -q '^server:' /var/lib/rancher/k3s/server/cred/passwd || echo 'passwd file lacks server entry'

if err != nil && strings.Contains(err.Error(), "server token not found") {
    // halt rotation, restore server/cred/passwd from backup, retry
}

When it happens

Trigger: 'k3s token rotate' (PUT /v1-k3s/token) on a server whose passwd file is missing, truncated, or lacks a line starting with 'server:' - e.g. after manual deletion, a partial restore, or copying cred/ files between nodes incorrectly.

Common situations: Operators pruning or regenerating files under server/cred; backups restored without the passwd file; mixing credential files from different installs.

Related errors

• method not allowed
• --token is required
• no bootstrap data found in datastore - check server token va
• found multiple bootstrap keys in storage
• bootstrap data already found and encrypted with different to

AI-assisted analysis of k3s-io/k3s@6ba341e396 (2026-08-15). Data as JSON: /api/errors/339014789462be1c. Report an issue: GitHub.