openai/codex-plugin-cc · error · Error

A prompt is required for this Codex run.

Error message

A prompt is required for this Codex run.

What it means

Thrown by runAppServerTurn when the effective prompt is empty. The effective prompt is options.prompt?.trim() falling back to options.defaultPrompt; if both are empty/whitespace, there is nothing for turn/start to execute, so the run is aborted before contacting the model.

Source

Thrown at plugins/codex/scripts/lib/codex.mjs:1129

      threadId = response.thread.id;
    } else {
      emitProgress(options.onProgress, "Starting Codex task thread.", "starting");
      const response = await startThread(client, cwd, {
        model: options.model,
        sandbox: options.sandbox,
        ephemeral: options.persistThread ? false : true,
        threadName: options.persistThread ? options.threadName : options.threadName ?? null
      });
      threadId = response.thread.id;
    }

    emitProgress(options.onProgress, `Thread ready (${threadId}).`, "starting", {
      threadId
    });

    const prompt = options.prompt?.trim() || options.defaultPrompt || "";
    if (!prompt) {
      throw new Error("A prompt is required for this Codex run.");
    }

    const turnState = await captureTurn(
      client,
      threadId,
      () =>
        client.request("turn/start", {
          threadId,
          input: buildTurnInput(prompt),
          model: options.model ?? null,
          effort: options.effort ?? null,
          outputSchema: options.outputSchema ?? null
        }),
      { onProgress: options.onProgress }
    );

    return {
      status: buildResultStatus(turnState),

View on GitHub (pinned to db52e28f4d)

Solutions

1. Provide a non-empty options.prompt (after trim) when calling runAppServerTurn.
2. If using a fallback, set options.defaultPrompt to a meaningful string.
3. Validate the prompt is non-blank in the caller before invoking the run.
4. If the prompt is genuinely empty, surface a clearer upstream error rather than calling the API.

Example fix

// before
await runAppServerTurn(cwd, { prompt: '   ' }) // throws
await runAppServerTurn(cwd, {}) // throws

// after
await runAppServerTurn(cwd, { prompt: 'Review the auth module for SSRF risks.' })
// or
await runAppServerTurn(cwd, { defaultPrompt: 'Summarize recent commits.' })

function effectivePrompt(options) {
  const p = (options?.prompt ?? '').trim();
  return p || (options?.defaultPrompt ?? '').trim();
}
if (!effectivePrompt(options)) {
  throw new Error('Cannot run Codex turn without a prompt');
}

function hasRunnablePrompt(o) {
  return Boolean((o?.prompt ?? '').trim() || (o?.defaultPrompt ?? '').trim());
}

null

When it happens

Trigger: Calling runAppServerTurn(cwd, { prompt: ' ' }) with no defaultPrompt, or runAppServerTurn(cwd, {}) when neither prompt nor defaultPrompt is supplied. Also when options.prompt is an empty string explicitly.

Common situations: A slash-command template produced an empty prompt. User submitted only whitespace. A caller relied on defaultPrompt but forgot to set it. Prompt construction stripped all content (e.g. an empty heredoc).

Related errors

• A Claude session source path is required.
• Unsupported reasoning effort "${effort}". Use one of: none,
• Choose either --enable-review-gate or --disable-review-gate.
• Codex CLI is not installed or is missing required runtime su
• This `/codex:review` target is not supported by the built-in

AI-assisted analysis of openai/codex-plugin-cc@db52e28f4d (2026-08-13). Data as JSON: /api/errors/a30c085889755e08. Report an issue: GitHub.