slopus/happy · error · LocalResumeSessionError

not_found

not_found

Error message

Cannot resume Happy session "${sessionId}" on this machine: no local session encryption data found at ${configuration.sessionsFile}. Start a new Happy session on this machine to enable future resumes.

What it means

resolveLocalReconnectableSession throws LocalResumeSessionError with code 'not_found' when readPersistedSessions() returns no records: the local sessions file (configuration.sessionsFile) contains no session encryption data at all. Local-only resume works exclusively from records in that file, so with zero records there is nothing to resume from.

Source

Thrown at packages/happy-cli/src/resume/localResumeStore.ts:82

    } catch (error) {
        if (error instanceof AxiosError && error.response?.status === 401) {
            throw new LocalResumeSessionError(
                'Happy session lookup authentication expired. Run `happy auth login --force` in this environment.',
                'unavailable',
            );
        }
        return null;
    }
}

export async function resolveLocalReconnectableSession(sessionId: string): Promise<ReconnectableHappySession> {
    const records = Object.entries(readPersistedSessions()).map(([id, session]) => ({
        id,
        ...session,
    }));

    if (records.length === 0) {
        throw new LocalResumeSessionError(
            `Cannot resume Happy session "${sessionId}" on this machine: no local session encryption data found at ${configuration.sessionsFile}. Start a new Happy session on this machine to enable future resumes.`,
            'not_found',
        );
    }

    let matched: PersistedSessionRecord;
    try {
        matched = resolveSessionRecordByPrefix(records, sessionId);
    } catch (error) {
        const message = error instanceof Error ? error.message : `No Happy session found matching "${sessionId}"`;
        throw new LocalResumeSessionError(
            `${message}. Only sessions stored in ${configuration.sessionsFile} can be resumed without legacy account credentials.`,
            message.startsWith('Ambiguous') ? 'ambiguous' : 'not_found',
        );
    }

    const encryptionKey = decodeBase64(matched.encryptionKey);
    let metadata = parseResumableMetadata(matched.id, matched.metadata);

View on GitHub (pinned to b824cd0a46)

Solutions

Start a new Happy session on this machine to populate the sessions file, enabling future resumes
Verify configuration.sessionsFile points at the file that actually contains your sessions (check env/config overrides)
Copy/restore the sessions file from the machine where the session was created (with its encryption keys)
Check you are running as the same OS user that created the sessions

Example fix

// before (fresh machine)
happy resume abc123  // sessionsFile empty
// after
happy  # start a session on this machine to seed sessionsFile
# or restore the original sessions file, then
happy resume abc123

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync, readFileSync } from 'node:fs';
const sessionsFile = configuration.sessionsFile;
if (!existsSync(sessionsFile)) {
  console.error(`No sessions file at ${sessionsFile}; start a happy session first.`);
  process.exit(1);
}
const records = Object.keys(JSON.parse(readFileSync(sessionsFile, 'utf8')));
if (records.length === 0) {
  console.error('sessionsFile has no records; start a happy session on this machine.');
  process.exit(1);
}

Try / catch

try {
  await handleResumeCommand([sessionId]);
} catch (e) {
  if (e instanceof LocalResumeSessionError && e.code === 'not_found') {
    console.error(e.message); // explains sessionsFile requirement
    process.exit(1);
  }
  throw e;
}

Prevention

Start at least one Happy session on each machine before expecting resume to work
Verify configuration.sessionsFile / env overrides point at the real sessions file
Back up the sessions file (it holds the encryption keys needed for resume)
Run resume as the same OS user that created the sessions

When it happens

Trigger: Running `happy resume <id>` on a machine whose sessions file is empty or missing entries — e.g. the file was deleted, HAPPY_ env vars/config point at a different sessionsFile than the one containing sessions, or resume is attempted on a fresh machine that never started a session locally.

Common situations: New laptop/container without prior Happy sessions; wiped config directory; pointing configuration at a non-default sessionsFile path by mistake; running as a different user whose HOME differs.

Understand the failure class

Background: NOT_FOUND error code: why tRPC, Harbor, Nacos and other libraries return 404 "not found" errors for resources that may still exist — this error's family across 11 libraries.

Related errors

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