What causes "HANDY_MASTER_SECRET is required" in slopus/happy?

Set HANDY_MASTER_SECRET in the environment before starting the server (export HANDY_MASTER_SECRET=$(openssl rand -hex 32) or add it to .env)

slopus/happy · critical

HANDY_MASTER_SECRET is required

Error message

HANDY_MASTER_SECRET is required

What it means

serve() refuses to start the standalone server when the HANDY_MASTER_SECRET environment variable is unset or empty. This secret is required to sign/encrypt session tokens, so without it the server cannot operate securely.

Source

Thrown at packages/happy-server/sources/standalone.ts:118

    }

    if (appliedCount === 0) {
        console.log("No new migrations to apply.");
    } else {
        console.log(`Applied ${appliedCount} migration(s).`);
    }

    await pg.close();
}

async function serve() {
    // Ensure DB_PROVIDER is set for db.ts
    process.env.DB_PROVIDER = process.env.DB_PROVIDER || "pglite";
    process.env.PGLITE_DIR = process.env.PGLITE_DIR || pgliteDir;

    const masterSecret = process.env.HANDY_MASTER_SECRET;
    if (!masterSecret) {
        throw new Error("HANDY_MASTER_SECRET is required");
    }

    const port = process.env.PORT ? parseInt(process.env.PORT, 10) : 3005;
    const host = process.env.HOST || "0.0.0.0";
    const staticDir = findStaticDir();
    let injectHtmlConfig: Record<string, unknown> | undefined;
    if (process.env.HAPPY_INJECT_HTML_CONFIG) {
        try {
            injectHtmlConfig = JSON.parse(process.env.HAPPY_INJECT_HTML_CONFIG);
        } catch {
            // ignore malformed input
        }
    }

    const { startServer } = await import("./index");
    await startServer({
        pgliteDir: process.env.PGLITE_DIR!,
        masterSecret,

View on GitHub (pinned to b824cd0a46)

Solutions

Set HANDY_MASTER_SECRET in the environment before starting the server (export HANDY_MASTER_SECRET=$(openssl rand -hex 32) or add it to .env)
If running in Docker/CI, pass the variable explicitly (docker run -e HANDY_MASTER_SECRET=... / secrets manager)
Check for typos and that the .env file is actually loaded from the expected working directory

Example fix

// before
$ npx happy-server
Error: HANDY_MASTER_SECRET is required
// after
$ export HANDY_MASTER_SECRET=$(openssl rand -hex 32)
$ npx happy-server

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.HANDY_MASTER_SECRET) {
  throw new Error('HANDY_MASTER_SECRET is required (export HANDY_MASTER_SECRET=$(openssl rand -hex 32))');
}

Prevention

Add HANDY_MASTER_SECRET to your .env and commit .env.example documenting it
Use a secrets manager in Docker/CI and pass the var explicitly
Validate required env vars at process start with a schema library (zod/env-var)
Check for typos: the variable is HANDY_MASTER_SECRET, not HAPPY_MASTER_SECRET

When it happens

Trigger: Starting the standalone happy-server (e.g. via the CLI's happyServer launcher) without HANDY_MASTER_SECRET in the environment, or with it set to an empty string.

Common situations: Missing .env file in the working directory; running the server in Docker/CI where the env var wasn't passed through; typo in the variable name (e.g. HAPPY_MASTER_SECRET); relying on a default that was removed in a newer version.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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