ComposioHQ/composio · error · Error

proxy() requires a non-empty toolkit string.

Error message

proxy() requires a non-empty toolkit string.

What it means

The proxy() helper's first argument is a toolkit name string. normalizeProxyToolkit throws when the value is not a string or trims to empty, before any network call is made.

Source

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

    } else if (Predicate.isRecord(inputSchema)) {
      structuredSchema = inputSchema;
    } else {
      throw new Error('experimental_subAgent() schema must be a Zod schema or JSON Schema object.');
    }
  }
  return {
    ...(requestedTarget === undefined ? {} : { target: requestedTarget }),
    ...(typeof options.model === 'string' ? { model: options.model } : {}),
    ...(options.schema === undefined ? {} : { schema: options.schema }),
    ...(options.jsonSchema === undefined ? {} : { jsonSchema: options.jsonSchema }),
    ...(structuredSchema === undefined ? {} : { structuredSchema }),
    ...(zodSchema === undefined ? {} : { zodSchema }),
  };
};

const normalizeProxyToolkit = (toolkit: string) => {
  if (typeof toolkit !== 'string' || toolkit.trim().length === 0) {
    throw new Error('proxy() requires a non-empty toolkit string.');
  }
  return toolkit.trim();
};

const normalizeFetchHeaders = (headers: HeadersInit | undefined) => {
  if (!headers) return [];
  const normalized: Array<{ name: string; type: string; value: string }> = [];
  new Headers(headers).forEach((value, name) => {
    normalized.push({ name, type: 'header', value });
  });
  return normalized;
};

const normalizeFetchBody = async (body: unknown) => {
  if (body === undefined || body === null) return undefined;
  if (typeof body === 'string' || typeof body === 'number' || typeof body === 'boolean')
    return body;
  if (typeof Blob !== 'undefined' && body instanceof Blob) return await body.text();

View on GitHub (pinned to 64b1b85502)

Solutions

1. Pass a non-empty toolkit slug, e.g. proxy('github')
2. Default the variable: toolkitName || 'github'
3. Log/validate the toolkit name at config load time when it comes from user input

Example fix

// before
const tk = process.env.TOOLKIT ?? '';
proxy(tk);
// after
const tk = process.env.TOOLKIT;
if (!tk) throw new Error('TOOLKIT env var is required');
proxy(tk);

if (typeof toolkit !== 'string' || toolkit.trim().length === 0) throw new RangeError('toolkit slug required');
proxy(toolkit);

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

When it happens

Trigger: Calling proxy('') , proxy(' '), or passing a non-string (undefined variable, number, null) as the toolkit slug.

Common situations: Toolkit name read from config/env that is unset or blank; template literal producing empty string; passing a toolkit object instead of its slug name.

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

• Could not determine a home directory to store the Composio c
• Failed to fetch file from URL: {_sanitize_url_for_logging(ur
• proxy_execute: toolkit is required
• proxy_execute: endpoint is required
• proxy fetch requires a non-empty URL string or URL object.

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