ComposioHQ/composio · error · ComposioToolkitFetchError

TOOLKIT_FETCH_ERROR

TOOLKIT_FETCH_ERROR

Error message

Failed to fetch toolkit

What it means

ComposioToolkitFetchError (code TOOLKIT_FETCH_ERROR): thrown when the HTTP request to fetch a toolkit fails (network error, auth failure, or server error) — distinct from TOOLKIT_NOT_FOUND which is a 404-style miss. Suggested fixes include validating the slug, API key, and base URL.

Source

Thrown at ts/packages/core/src/errors/ToolkitErrors.ts:30

    super(message, {
      ...options,
      code: 'TOOLKIT_NOT_FOUND',
      possibleFixes: options.possibleFixes || [
        'Ensure the toolkit is correctly configured and the slug is valid',
      ],
    });
    this.name = 'ComposioToolkitNotFoundError';
  }
}

export class ComposioToolkitFetchError extends ComposioError {
  constructor(
    message: string = 'Failed to fetch toolkit',
    options: Omit<ComposioErrorOptions, 'code' | 'statusCode'> = {}
  ) {
    super(message, {
      ...options,
      code: 'TOOLKIT_FETCH_ERROR',
      possibleFixes: options.possibleFixes || [
        'Ensure the toolkit slug is valid',
        'Ensure you are using the correct API key',
        'Ensure you are using the correct API endpoint / Base URL and it is working',
      ],
    });
    this.name = 'ComposioToolkitFetchError';
  }
}

View on GitHub (pinned to 64b1b85502)

Solutions

1. Verify the API key is valid for the endpoint you're using
2. Check baseUrl configuration matches the key's environment
3. Retry with backoff — transient 5xx/network failures often resolve
4. Catch by code TOOLKIT_FETCH_ERROR and distinguish from TOOLKIT_NOT_FOUND

Example fix

// before
new Composio({ apiKey: process.env.COMPOSIO_API_KEY }) // unset var -> fetch fails
// after
const apiKey = process.env.COMPOSIO_API_KEY;
if (!apiKey) throw new Error('COMPOSIO_API_KEY missing');
new Composio({ apiKey });

if (!process.env.COMPOSIO_API_KEY) throw new Error('missing key');

import { ComposioToolkitFetchError } from '@composio/core/errors';
const isFetchError = (e: unknown): boolean => e instanceof ComposioToolkitFetchError;

try { ... } catch (e) { if (e instanceof ComposioToolkitFetchError) await retryWithBackoff(fn, 3); else throw e; }

When it happens

Trigger: composio.toolkits.get(slug) when the API key is invalid/expired, the base URL points to a wrong/unreachable endpoint, network is down, or the backend returns 5xx.

Common situations: Wrong apiKey or env var; custom baseUrl misconfigured (e.g. pointing at staging when key is prod); proxies/firewalls blocking api URLs; backend outages.

Related errors

• TOOLKIT_NOT_FOUND
• Couldn't fetch Toolkit with slug: ${slug}
• Could not determine a home directory to store the Composio c
• Request timed out fetching URL: {_sanitize_url_for_logging(u
• Failed to fetch file from URL: {_sanitize_url_for_logging(ur

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