larksuite/cli · error

stored token data is corrupt

Error message

stored token data is corrupt

What it means

errStoredTokenCorrupt signals that a stored user access token could not be decoded back into a StoredUAToken struct — the persisted token blob is damaged, truncated, or was written by an incompatible format. readStoredToken wraps the decode failure with this sentinel, and GetValidAccessToken maps it to a NeedUserAuthorization error because a corrupt token is unusable and only re-authorization can recover it. The library throws it so callers can distinguish 'token corrupt' from 'token missing' and force an interactive re-auth.

Source

Thrown at internal/auth/token_store.go:30

	"github.com/larksuite/cli/errs"
	"github.com/larksuite/cli/internal/keychain"
)

// StoredUAToken represents a stored user access token.
type StoredUAToken struct {
	UserOpenId       string `json:"userOpenId"`
	AppId            string `json:"appId"`
	AccessToken      string `json:"accessToken"`
	RefreshToken     string `json:"refreshToken"`
	ExpiresAt        int64  `json:"expiresAt"`        // Unix ms
	RefreshExpiresAt int64  `json:"refreshExpiresAt"` // Unix ms
	Scope            string `json:"scope"`
	GrantedAt        int64  `json:"grantedAt"` // Unix ms
}

const refreshAheadMs = 5 * 60 * 1000 // 5 minutes

var errStoredTokenCorrupt = errors.New("stored token data is corrupt")

// accountKey generates a unique key for an account based on its AppID and UserOpenID.
func accountKey(appId, userOpenId string) string {
	return fmt.Sprintf("%s:%s", appId, userOpenId)
}

// MaskToken masks a token for safe logging.
func MaskToken(token string) string {
	if len(token) <= 8 {
		return "****"
	}
	return "****" + token[len(token)-4:]
}

// GetStoredToken reads the stored UAT for a given (appId, userOpenId) pair.
func GetStoredToken(appId, userOpenId string) *StoredUAToken {
	token, _ := readStoredToken(appId, userOpenId)
	return token

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Re-authenticate the user: run the CLI's authorization flow so the token is rewritten (GetValidAccessToken already surfaces NeedUserAuthorization for this)
2. Delete the corrupt token entry for the affected appId:userOpenId and log in again
3. Check disk space and file permissions on the token store location
4. If reproducible across versions, report the token schema change

Example fix

// before
stored, err := readStoredToken(appId, openId)
if err != nil { return err }
// after
stored, err := readStoredToken(appId, openId)
if errors.Is(err, errStoredTokenCorrupt) {
    return newNeedUserAuthorizationError(openId, err, recovery.UserAuthorization())
}

// verify stored token decodes before use
if _, err := readStoredToken(appId, openId); errors.Is(err, errStoredTokenCorrupt) {
    // token file unreadable — require re-auth
}

func isCorruptToken(err error) bool { return errors.Is(err, errStoredTokenCorrupt) }

token, err := GetValidAccessToken(client, opts)
if errors.Is(err, errStoredTokenCorrupt) {
    return reauthorize(opts.UserOpenId) // map to NeedUserAuthorization
}

When it happens

Trigger: Calling GetValidAccessToken (or readStoredToken) when the token file/record for appId:userOpenId contains bytes that fail JSON unmarshal — e.g. partial write, manual tampering, or format change across CLI versions.

Common situations: Disk full during token write; user edited or deleted part of the token store; upgrading lark-cli after the stored token schema changed; a sandbox/backup tool mangled the token file.

Related errors

• failed to parse user info: %w
• failed to get user info [%d]: %s
• failed to get user info: missing open_id in response
• failed to parse response: %w
• %w: %w

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/8d2cc5a43a72ddae. Report an issue: GitHub.