mastra-ai/mastra · error

--continue and --thread cannot be used together

Error message

--continue and --thread cannot be used together

What it means

parseHeadlessArgs() enforces that the --continue and --thread CLI flags are mutually exclusive: --continue implicitly resumes the most recent thread, while --thread names a specific one, and both together are ambiguous. When both are set it throws during argument parsing, before any agent runs.

Source

Thrown at mastracode/sdk/src/headless/cli.ts:113

  for (const flag of FLAGS) {
    if (!flag.field) continue; // e.g. --help, handled by the caller
    const raw = values[flag.key];
    if (raw === undefined) continue;

    if (flag.type === 'boolean') {
      sink[flag.field] = Boolean(raw);
    } else if (typeof raw === 'string') {
      sink[flag.field] = flag.coerce ? flag.coerce(raw) : raw;
    }
  }

  // A bare positional acts as the prompt when --prompt/-p is absent.
  if (args.prompt === undefined && positionals[0] !== undefined) {
    args.prompt = positionals[0];
  }

  if (args.continue_ && args.thread) {
    throw new Error('--continue and --thread cannot be used together');
  }

  return args;
}

export function printHeadlessUsage(): void {
  process.stdout.write(`
Usage: mastracode --prompt <text> [options]

Headless (non-interactive) mode options:
${renderFlagUsage()}

Thread behavior:
  By default, a new thread is created for each run.
  Use --continue to resume the most recent thread, or --thread to target a specific one.
  Use --clone-thread to branch off a copy before running.

Settings file:

View on GitHub (pinned to 75dd419e61)

Solutions

1. Drop --continue and keep --thread <id> when you know which thread to resume.
2. Drop --thread and keep --continue when you want the most recent thread.
3. In wrapper scripts, reject the combination early and print usage via printHeadlessUsage().

Example fix

// before
mastracode --continue --thread thread_42 -p "summarize"
// after
mastracode --thread thread_42 -p "summarize"

if (argv.includes('--continue') && (argv.includes('--thread') || argv.some(a => a.startsWith('--thread=')))) {
  throw new Error('--continue and --thread cannot be used together');
}

null

let args;
try {
  args = parseHeadlessArgs(rawArgs);
} catch (err) {
  console.error(String(err.message));
  printHeadlessUsage();
  process.exit(2);
}

When it happens

Trigger: Running the headless CLI with both flags, e.g. `mastracode --continue --thread abc123 ...`, or programmatic parsing of an args object where continue_ and thread are both populated (scripts that append flags conditionally).

Common situations: Shell aliases/wrappers that already bake in --continue while the user adds --thread; CI scripts concatenating flag arrays; migration from an older invocation pattern where --thread was assumed compatible with --continue.

Related errors

• Invalid --region "${region}". Expected one of: eu, us.
• ${err instanceof Error ? err.message : String(err)}\nYou can
• No organization matched --org "${value}". Available: ${avail
• Directory ${path.basename(targetPath)} already exists
• ${flag} must be one of: ${allowed.join(', ')}

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/0a4994fe9a824179. Report an issue: GitHub.