garrytan/gstack · warning · Error

Unknown flag: ${args[i]}

Error message

Unknown flag: ${args[i]}

What it means

Unknown-flag guard at write-commands.ts:224-226. The argument loop only recognizes --from-file and --wait-until (tab-id is handled upstream by the dispatcher). Any other token starting with -- is rejected to surface typos rather than silently ignoring them.

Source

Thrown at browse/src/write-commands.ts:225

          let json: any;
          try { json = JSON.parse(raw); }
          catch (e: any) { throw new Error(`load-html: --from-file JSON parse failed: ${e.message}`); }
          if (typeof json.html !== 'string') {
            throw new Error('load-html: --from-file JSON must have a "html" string field');
          }
          if (json.waitUntil && json.waitUntil !== 'load'
              && json.waitUntil !== 'domcontentloaded' && json.waitUntil !== 'networkidle') {
            throw new Error(`load-html: --from-file waitUntil '${json.waitUntil}' invalid`);
          }
          fromFilePayload = { html: json.html, waitUntil: json.waitUntil };
        } else if (args[i] === '--wait-until') {
          const val = args[++i];
          if (val !== 'load' && val !== 'domcontentloaded' && val !== 'networkidle') {
            throw new Error(`Invalid --wait-until '${val}'. Must be one of: load, domcontentloaded, networkidle.`);
          }
          waitUntil = val;
        } else if (args[i].startsWith('--')) {
          throw new Error(`Unknown flag: ${args[i]}`);
        } else if (!filePath) {
          filePath = args[i];
        }
      }

      // Inline HTML path: validate size + magic byte, then setContent directly.
      if (fromFilePayload) {
        const MAX_BYTES = parseInt(process.env.GSTACK_BROWSE_MAX_HTML_BYTES || '', 10) || (50 * 1024 * 1024);
        if (Buffer.byteLength(fromFilePayload.html, 'utf8') > MAX_BYTES) {
          throw new Error(
            `load-html: --from-file html too large (> ${MAX_BYTES} bytes). ` +
            'Raise with GSTACK_BROWSE_MAX_HTML_BYTES=<N>.'
          );
        }
        const peek = fromFilePayload.html.trimStart();
        if (!/^<[a-zA-Z!?]/.test(peek)) {
          throw new Error('load-html: --from-file html does not start with a valid markup opener');
        }

View on GitHub (pinned to 94993f7401)

Solutions

1. Use only the supported flags: --from-file <path> and --wait-until <value>
2. Check the usage string (thrown when no file path is given) for the full grammar
3. Correct the typo

Example fix

// before
load-html --fromfile ./p.json
// after
load-html --from-file ./p.json

const KNOWN_FLAGS = new Set(['--from-file','--wait-until'])
function onlyKnownFlags(args: string[]): boolean {
  return args.every(a => !a.startsWith('--') || KNOWN_FLAGS.has(a))
}

When it happens

Trigger: A misspelled or unsupported flag: --fromfile, --file, --wait, --url, --content, --source, --output.

Common situations: Typo in a flag name; using a flag from a different command; assuming an option exists because a sibling command has it.

Related errors

• load-html: --from-file requires a path
• Usage: browse goto <url>
• Invalid --wait-until '${val}'. Must be one of: load, domcont
• Cannot use load-html inside a frame. Run 'frame main' first.
• load-html: --from-file ${payloadPath} must be under ${SAFE_D

AI-assisted analysis of garrytan/gstack@94993f7401 (2026-08-12). Data as JSON: /api/errors/38f804c91f9d3029. Report an issue: GitHub.