slopus/happy · error

Happy session ID is required: happy resume <session-id>

Error message

Happy session ID is required: happy resume <session-id>

What it means

resolveSessionRecordByPrefix matches a user-supplied session ID prefix against known Happy session records. Before filtering it trims the input, and if nothing remains it throws this error because an empty prefix would match every (or no) session and resume is impossible without an ID. The message doubles as usage guidance pointing to `happy resume <session-id>`.

Source

Thrown at packages/happy-cli/src/resume/resolveHappySession.ts:62

export type ResumableHappySession = {
    id: string;
    active: boolean;
    metadata: Metadata;
};

export type ReconnectableHappySession = ResumableHappySession & {
    seq: number;
    metadataVersion: number;
    agentStateVersion: number;
    encryptionKey: Uint8Array;
    encryptionVariant: 'legacy' | 'dataKey';
};

export function resolveSessionRecordByPrefix<T extends { id: string }>(records: T[], sessionId: string): T {
    const trimmed = sessionId.trim();
    if (!trimmed) {
        throw new Error('Happy session ID is required: happy resume <session-id>');
    }

    const matches = records.filter((record) => record.id.startsWith(trimmed));
    if (matches.length === 0) {
        throw new Error(`No Happy session found matching "${trimmed}"`);
    }
    if (matches.length > 1) {
        throw new Error(`Ambiguous Happy session "${trimmed}" matches ${matches.length} sessions. Be more specific.`);
    }
    return matches[0];
}

function decryptBoxBundle(bundle: Uint8Array, recipientSecretKey: Uint8Array): Uint8Array | null {
    if (bundle.length < 56) {
        return null;
    }

    const ephemeralPublicKey = bundle.slice(0, 32);

View on GitHub (pinned to b824cd0a46)

Solutions

1. Pass a session ID: run `happy resume <session-id>` with at least a non-empty prefix of the session ID.
2. Check the wrapper/script for an unset or empty variable holding the session ID and quote it: happy resume "$SESSION_ID".
3. List available sessions first to find a valid ID, then resume with that ID.

Example fix

// before
const id = process.argv[2] ?? '';
await resolveHappySession(id);
// after
const id = process.argv[2]?.trim();
if (!id) {
  console.error('Usage: happy resume <session-id>');
  process.exit(1);
}
await resolveHappySession(id);

const id = (sessionId ?? '').trim();
if (!id) throw new Error('Usage: happy resume <session-id>');

When it happens

Trigger: Calling resolveSessionRecordByPrefix(records, sessionId) with an empty string, a whitespace-only string, or indirectly via happy resume when no session-id argument is provided.

Common situations: Running `happy resume` with no argument in a shell script or CI pipeline; a wrapper script losing the argument due to unquoted variable expansion ($1 unset); copy-paste that dropped the ID.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Unexpected arguments for happy resume: ${args.slice(1).join(
• Usage: happy acp <agent-name> or happy acp -- <command> [arg
• Missing command after "--". Usage: happy acp -- <command> [a
• Resume session handler not available
• Daemon-spawned sessions cannot use local/interactive mode. U

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