Happy session ${session.id} uses unsupported flavor "${metad

Error message

Happy session ${session.id} uses unsupported flavor "${metadata.flavor ?? 'unknown'}".

What it means

buildResumeLaunch throws this when resolveFlavor(metadata) returns a flavor that is neither 'codex' nor 'claude'. The switch only handles those two flavors; anything else (including undefined metadata.flavor, rendered as 'unknown') is explicitly unsupported for resume.

Source

Thrown at packages/happy-cli/src/resume/handleResumeCommand.ts:89

    if (flavor === 'claude') {
        if (!metadata.claudeSessionId) {
            throw new Error(`Happy session ${session.id} is missing its Claude session ID.`);
        }
        const args = ['claude'];
        if (options.claudeStartingMode) {
            args.push('--happy-starting-mode', options.claudeStartingMode);
        }
        if (options.startedBy) {
            args.push('--started-by', options.startedBy);
        }
        args.push('--resume', metadata.claudeSessionId);
        return {
            cwd: metadata.path,
            args,
        };
    }

    throw new Error(`Happy session ${session.id} uses unsupported flavor "${metadata.flavor ?? 'unknown'}".`);
}

export function formatResumeHelp(): string {
    return [
        'happy resume - Resume a previous Happy session',
        '',
        'Usage:',
        '  happy resume <happy-session-id>',
        '',
        'Examples:',
        '  happy resume cmmij8olq00dp5jcxr3wtbpau',
        '  happy resume cmmij8',
        '',
        'This reuses the saved worktree/path and resumes the underlying agent session',
        'when the backend supports it.',
    ].join('\n');
}

View on GitHub (pinned to b824cd0a46)

Solutions

Upgrade happy-cli to the latest version so it recognizes the flavor written by the session's original CLI
Check metadata.flavor for typos if you manage the sessions file manually
Start a new session with a supported flavor (claude or codex)
Inspect decrypted session metadata to confirm the flavor value stored for this session

Example fix

// before (older CLI reading newer metadata)
flavor: "gemini"  // -> unsupported flavor "gemini"
// after
npm i -g happy-coder@latest && happy resume <session-id>

Defensive patterns

Strategy: validation

Validate before calling

const SUPPORTED_FLAVORS = ['claude', 'codex'] as const;
function isResumableFlavor(m: Metadata): boolean {
  return SUPPORTED_FLAVORS.includes(resolveFlavor(m) as any);
}
if (!isResumableFlavor(session.metadata)) {
  console.error('Unsupported flavor; upgrade happy-cli.');
  process.exit(1);
}

Type guard

function isSupportedFlavor(m: Metadata): m is Metadata & { flavor: 'claude' | 'codex' } {
  const f = resolveFlavor(m);
  return f === 'claude' || f === 'codex';
}

Try / catch

try {
  const launch = buildResumeLaunch(session);
} catch (e) {
  if (e instanceof Error && e.message.includes('unsupported flavor')) {
    console.error(e.message + ' — upgrade happy-cli to support this session type.');
    return;
  }
  throw e;
}

Prevention

Run the latest happy-cli so all flavors written by newer sessions are recognized
Whitelist known flavors before attempting resume
Avoid manually editing the flavor field in persisted metadata
Check release notes when downgrading CLI versions

When it happens

Trigger: Calling buildResumeLaunch with metadata.flavor set to an unrecognized string (typo, newer CLI writing a flavor this version doesn't know, e.g. 'gemini'), or flavor missing entirely so it falls through both if-branches.

Common situations: Downgraded happy-cli reading metadata written by a newer version with a new flavor; manually edited sessions file with a bad flavor value; corrupted decrypted metadata where ResumableMetadataSchema allowed an unknown flavor string.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of slopus/happy@b824cd0a46 (2026-08-31). Data as JSON: /api/errors/b4ecfe210f756696. Report an issue: GitHub.