What causes "id must be a non-empty session ID or grok.com chat URL" in jackwener/OpenCLI?

Pass a valid Grok conversation UUID (8-4-4-4-12 hex) or a grok.com/c/ URL.

jackwener/OpenCLI · error · ArgumentError

id must be a non-empty session ID or grok.com chat URL

Error message

id must be a non-empty session ID or grok.com chat URL

What it means

parseGrokSessionId normalizes user input into a Grok conversation id (UUID v4 shape) and throws ArgumentError when the input is empty after trimming. The caller must supply either a bare session UUID or a grok.com chat URL from which the UUID can be extracted.

Source

Thrown at clis/grok/utils.js:37

        GROK_DOMAIN,
        detail || 'Sign in to grok.com in your browser, then retry.',
    );
}

export function normalizeBooleanFlag(value, fallback = false) {
    if (typeof value === 'boolean') return value;
    if (value == null || value === '') return fallback;
    const normalized = String(value).trim().toLowerCase();
    return normalized === 'true' || normalized === '1' || normalized === 'yes' || normalized === 'on';
}

// UUID v4-shape: 8-4-4-4-12 hex with dashes (the format Grok uses for /c/<id>)
const GROK_SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

export function parseGrokSessionId(input) {
    const raw = String(input ?? '').trim();
    if (!raw) {
        throw new ArgumentError('id', 'must be a non-empty session ID or grok.com chat URL');
    }
    let candidate = raw;
    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
        let parsed;
        try {
            parsed = new URL(raw);
        } catch {
            throw new ArgumentError('id', `not a valid Grok URL (got "${input}")`);
        }
        const host = parsed.hostname.toLowerCase();
        const pathMatch = parsed.pathname.match(
            /^\/c\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/?$/i,
        );
        if (parsed.protocol !== 'https:' || (host !== 'grok.com' && !host.endsWith('.grok.com')) || !pathMatch) {
            throw new ArgumentError(
                'id',
                `not a valid Grok conversation URL (got "${input}"); expected https://grok.com/c/<id>`,
            );

View on GitHub (pinned to 49907e53dc)

Solutions

Pass a valid Grok conversation UUID (8-4-4-4-12 hex) or a grok.com/c/<id> URL.
Copy the id directly from the grok.com chat URL in the browser.
Fix the upstream script/variable so it actually contains the id before invoking the CLI.

Example fix

// before
cli pin --id "$CHAT_ID"   # CHAT_ID=''
// after
cli pin --id 'https://grok.com/c/123e4567-e89b-41d4-a716-446655440000'

Defensive patterns

Strategy: type-guard

Validate before calling

const GROK_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
const raw = String(input ?? '').trim();
if (!raw) throw new Error('id is required: pass a session UUID or a grok.com/c/<id> URL');
if (!GROK_ID_RE.test(raw) && !/^https:\/\/grok\.com\/c\//.test(raw)) {
  throw new Error(`unrecognized id format: ${raw}`);
}

Type guard

function isGrokSessionInput(v) {
  if (typeof v !== 'string') return false;
  const raw = v.trim();
  if (!raw) return false;
  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(raw) ||
    /^https:\/\/grok\.com\/c\//i.test(raw);
}

Try / catch

try {
  await cli.pin({ id });
} catch (e) {
  if (e instanceof ArgumentError && /non-empty session ID/.test(e.message)) {
    console.error(`Empty id supplied (value: ${JSON.stringify(id)}) — extract it from the grok.com chat URL.`);
    process.exitCode = 2;
  } else throw e;
}

Prevention

Extract the UUID from the grok.com/c/<id> URL rather than hand-copying.
Fail fast in scripts when the id variable is empty or null.
Validate id shape (UUID v4 regex) before calling any id-based command.
Avoid passing objects/undefined directly — stringify and trim first.

When it happens

Trigger: Calling commands that take an id (pin, unpin, open, etc.) with id='', id=undefined/null, or a whitespace-only string — the trim leaves raw empty and the guard fires before URL parsing.

Common situations: Script variable holding the id was never populated, a JSON/jq extraction returned null, or an upstream tool emitted an empty id field.

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

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/bfe0a0eacd1fcb72. Report an issue: GitHub.