slopus/happy · error · TmuxSessionIdentifierError

Invalid session name: "${sessionName}"

Error message

Invalid session name: "${sessionName}"

What it means

This session-creation helper validates the requested tmux session name against /^[a-zA-Z0-9._-]+$/ before running 'new-session'. Empty names or names with spaces/special characters are rejected with a TmuxSessionIdentifierError because tmux would fail or behave unpredictably.

Source

Thrown at packages/happy-cli/src/utils/tmux.ts:969

    } catch {
        return false;
    }
}

/**
 * Create a new tmux session with proper typing and validation
 */
export async function createTmuxSession(
    sessionName: string,
    options?: {
        windowName?: string;
        detached?: boolean;
        attach?: boolean;
    }
): Promise<{ success: boolean; sessionIdentifier?: string; error?: string }> {
    try {
        if (!sessionName || !/^[a-zA-Z0-9._-]+$/.test(sessionName)) {
            throw new TmuxSessionIdentifierError(`Invalid session name: "${sessionName}"`);
        }

        const utils = new TmuxUtilities(sessionName);
        const windowName = options?.windowName || 'main';

        const cmd = ['new-session'];
        if (options?.detached !== false) {
            cmd.push('-d');
        }
        cmd.push('-s', sessionName);
        cmd.push('-n', windowName);

        const result = await utils.executeTmuxCommand(cmd);
        if (result && result.returncode === 0) {
            const sessionIdentifier: TmuxSessionIdentifier = {
                session: sessionName,
                window: windowName
            };

View on GitHub (pinned to b824cd0a46)

Solutions

1. Sanitize the name before calling: replace invalid characters with '.' or '-', e.g. name.replace(/[^a-zA-Z0-9._-]/g, '-').
2. Provide a non-empty name explicitly instead of deriving it from an optional variable.
3. Validate with the same regex (/^[a-zA-Z0-9._-]+$/) before the call.
4. If the name comes from a path, strip directories and replace path separators.

Example fix

// before
await createSession(projectPath); // '/Users/me/My Project'
// after
const sessionName = path.basename(projectPath).replace(/[^a-zA-Z0-9._-]/g, '-');
await createSession(sessionName);

const SESSION_NAME_RE = /^[a-zA-Z0-9._-]+$/;
function assertValidSessionName(name) {
  if (!name || !SESSION_NAME_RE.test(name)) {
    throw new Error(`Session name must match ${SESSION_NAME_RE}, got: ${JSON.stringify(name)}`);
  }
}
assertValidSessionName(sessionName);

function isValidSessionName(name) {
  return typeof name === 'string' && name.length > 0 && /^[a-zA-Z0-9._-]+$/.test(name);
}

try {
  await createSession(sessionName, options);
} catch (e) {
  if (e instanceof TmuxSessionIdentifierError) {
    return { success: false, error: `Invalid session name: ${sessionName}` };
  }
  throw e;
}

When it happens

Trigger: Calling createSession (the exported helper around tmux.ts:969) with sessionName undefined, empty string '', or containing characters outside [a-zA-Z0-9._-], e.g. 'my project', 'dev:1', 'a/b'.

Common situations: Deriving a session name from a project path or branch name that contains spaces or slashes; an unset environment variable producing an empty name; passing a full tmux target string like 'sess:win' where a bare session name is expected.

Related errors

• Session identifier must be a non-empty string
• Invalid session identifier: missing session name
• Invalid session name: "${params.session}"
• Invalid window name: "${params.window}"
• Invalid pane identifier: "${params.pane}"

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