ComposioHQ/composio · error · Error

experimental_subAgent() requires a non-empty prompt string.

Error message

experimental_subAgent() requires a non-empty prompt string.

What it means

experimental_subAgent()'s first argument must be a non-empty string prompt; the implementation trims it and throws if it is not a string or is whitespace-only before doing any work.

Source

Thrown at ts/packages/cli/src/services/run-helpers-runtime.ts:835

  const resolveInvokeAgentTarget = (requestedTarget?: string): 'claude' | 'codex' => {
    if (requestedTarget === 'claude' || requestedTarget === 'codex') return requestedTarget;
    const configuredTarget = readConfiguredExperimentalSubagentTarget(helperContext.cliConfigPath);
    if (configuredTarget === 'claude' || configuredTarget === 'codex') return configuredTarget;
    const detected = requestedTarget === 'user' ? 'user' : detectInvokeAgentMaster();
    if (detected === 'codex' || detected === 'claude') return detected;
    if (typeof Bun.which === 'function' && Bun.which('codex')) return 'codex';
    if (typeof Bun.which === 'function' && Bun.which('claude')) return 'claude';
    throw new Error(
      'experimental_subAgent() could not determine an agent CLI. Current master is user; install codex or claude, or pass { target: "codex" | "claude" }.'
    );
  };

  const experimentalSubAgentImpl = async (
    prompt: string,
    options: Record<string, unknown> = {}
  ) => {
    if (typeof prompt !== 'string' || prompt.trim().length === 0) {
      throw new Error('experimental_subAgent() requires a non-empty prompt string.');
    }
    const logFilePath =
      typeof helperContext.runLogFilePath === 'string' && helperContext.runLogFilePath.length > 0
        ? helperContext.runLogFilePath
        : undefined;
    const normalizedOptions = normalizeInvokeAgentOptions(options);
    const target = resolveInvokeAgentTarget(normalizedOptions.target);
    const master = detectInvokeAgentMaster();
    helperDebugLog('subAgent.target', {
      requestedTarget: normalizedOptions.target ?? null,
      resolvedTarget: target,
      master,
    });
    const response = await invokeAcpSubAgent({
      prompt: prompt.trim(),
      options: normalizedOptions,
      master,
      target,

View on GitHub (pinned to 64b1b85502)

Solutions

1. Pass a non-empty prompt string
2. Guard dynamic prompts: if (!prompt?.trim()) return / throw early
3. Assemble the prompt with fallbacks, e.g. prompt ?? defaultPrompt

Example fix

// before
await experimental_subAgent(userInput); // userInput may be ''
// after
const prompt = userInput?.trim();
if (!prompt) throw new Error('Prompt is required');
await experimental_subAgent(prompt);

if (typeof prompt !== 'string' || prompt.trim().length === 0) throw new TypeError('prompt required');
await experimental_subAgent(prompt);

const isNonEmptyPrompt = (v: unknown): v is string => typeof v === 'string' && v.trim().length > 0;

When it happens

Trigger: Calling experimental_subAgent(''), experimental_subAgent(' '), or passing a non-string such as an array of messages, an object, or an undefined variable.

Common situations: Prompt built from a template whose variables are empty, optional user input passed through without a default, or passing a chat-messages array (OpenAI-style) instead of a plain prompt string.

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

• experimental_subAgent() target must be "claude", "codex", or
• experimental_subAgent() schema must be a Zod schema or JSON
• Could not determine a home directory to store the Composio c
• Cache directory {directory} is not writable please provide a
• module {__name__!r} has no attribute {name!r}

AI-assisted analysis of ComposioHQ/composio@64b1b85502 (2026-08-28). Data as JSON: /api/errors/b13b8a802dd7b5b0. Report an issue: GitHub.