ComposioHQ/composio · error · Error

ComposioClient is required

Error message

ComposioClient is required

What it means

Plain Error thrown by the Tools constructor when called without a ComposioClient instance. The Tools model is normally created for you by Composio, so hitting this usually means Tools was instantiated manually or a falsy client was passed in tests.

Source

Thrown at ts/packages/core/src/models/Tools.ts:128

    fileUploadPathDenySegments?: string[];
    fileUploadAllowlist?: string[];
    fileDownloadDir?: string;
  };
  /**
   * Tracks tool slugs we've already warned about to avoid spamming the log when
   * the same file-input tool is executed repeatedly while auto-upload is off.
   * Scoped per-instance so a fresh `Composio` starts with a clean slate.
   */
  private readonly warnedAutoUploadDisabledForTool = new Set<string>();

  /**
   * Lazily-built sibling client with retries disabled; see `clientWithoutRetries`.
   */
  private clientWithoutRetriesCache?: ComposioClient;

  constructor(client: ComposioClient, config?: ComposioConfig<TProvider>) {
    if (!client) {
      throw new Error('ComposioClient is required');
    }
    if (!config?.provider) {
      throw new ComposioProviderNotDefinedError('Provider not passed into Tools instance');
    }

    this.client = client;
    this.provider = config.provider;
    this.autoUploadDownloadFiles = config?.dangerouslyAllowAutoUploadDownloadFiles === true;
    this.toolkitVersions = config?.toolkitVersions ?? CONFIG_DEFAULTS.toolkitVersions;
    this.fileUploadPathOptions = {
      sensitiveFileUploadProtection: config?.sensitiveFileUploadProtection,
      fileUploadPathDenySegments: config?.fileUploadPathDenySegments,
      // The allowlist is only enforced during automatic upload (see
      // FileToolModifier). Manual `composio.files.upload()` calls don't see it.
      fileUploadAllowlist: this.autoUploadDownloadFiles
        ? resolveEffectiveUploadAllowlist(config?.fileUploadDirs)
        : undefined,
      fileDownloadDir: config?.fileDownloadDir,

View on GitHub (pinned to 64b1b85502)

Solutions

1. Use composio.tools (the instance property) instead of constructing Tools manually.
2. If constructing manually, pass a valid ComposioClient: const tools = new Tools(composio, { provider }).
3. In tests, provide a mock client object implementing the ComposioClient surface used by Tools.

Example fix

// before
const tools = new Tools(undefined, { provider: 'openai' });

// after
const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY!, provider: 'openai' });
const tools = composio.tools;

if (!client) throw new TypeError('client must be a ComposioClient');
const tools = new Tools(client, { provider });

const isComposioClient = (c: unknown): c is ComposioClient =>
  !!c && typeof c === 'object' && 'tools' in c;

When it happens

Trigger: new Tools(undefined as any, { provider }) — manually constructing Tools without a client, or passing a client variable that is undefined due to failed initialization.

Common situations: Unit tests constructing Tools directly; refactoring that loses the client reference; calling new Composio(...) incorrectly so the returned client is undefined.

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

• Provider not passed into Tools instance
• Invalid beforeExecute modifier. Not a function.
• experimental_subAgent() target must be "claude", "codex", or
• Interactive permission prompts are disabled in this environm
• Invalid Composio CLI release tag: ${releaseTag}

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