Toolkit versioning migration
Starting with Python SDK v0.9.0 and TypeScript SDK v0.2.0, manual tool execution requires explicit version specification. This is a breaking change from earlier versions where toolkit versioning was optional.
Breaking change
Manual tool execution now requires explicit version specification. The tools.execute() method will fail without a version.
Before (will fail)
# Raises ToolVersionRequiredError
result = composio.tools.execute(
"GITHUB_CREATE_ISSUE",
{"user_id": "user-123", "arguments": {...}}
)// Throws ComposioToolVersionRequiredError
const result = await composio.tools.execute({
toolSlug: "GITHUB_CREATE_ISSUE",
userId: "user-123",
arguments: {...}
});After (required)
Choose one of three migration strategies:
Option 1: Configure version at SDK level
from composio import Composio
# Pin specific versions for each toolkit
composio = Composio(
api_key="YOUR_API_KEY",
toolkit_versions={
"github": "20251027_00",
"slack": "20251027_00",
"gmail": "20251027_00"
}
)import { Composio } from "@composio/core";
// Pin specific versions for each toolkit
const composio = new Composio({
apiKey: "YOUR_API_KEY",
toolkitVersions: {
github: "20251027_00",
slack: "20251027_00",
gmail: "20251027_00"
}
});Option 2: Pass version with each execution
# Specify version directly in execute call
result = composio.tools.execute(
"GITHUB_LIST_STARGAZERS",
arguments={
"owner": "ComposioHQ",
"repo": "composio"
},
user_id="user-k7334",
version="20251027_00" # Override version for this execution
)
print(result)// Specify version directly in execute call
const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {
userId: "user-k7334",
arguments: {
owner: "ComposioHQ",
repo: "composio"
},
version: "20251027_00" // Override version for this execution
});
console.log(result);Option 3: Use environment variables
export COMPOSIO_TOOLKIT_VERSION_GITHUB="20251027_00"Migration checklist
- Audit your code: Find all
tools.execute()calls in your codebase - Choose a strategy: Select one of the three options above based on your needs
- Test thoroughly: Verify tools work correctly with pinned versions
- Deploy gradually: Roll out changes incrementally to minimize risk
Temporary workaround
During migration, you can temporarily skip version checks (not recommended for production):
result = composio.tools.execute(
"GITHUB_CREATE_ISSUE",
{
"user_id": "user-123",
"arguments": {...}
},
dangerously_skip_version_check=True
)const result = await composio.tools.execute({
toolSlug: "GITHUB_CREATE_ISSUE",
userId: "user-123",
arguments: {...},
dangerouslySkipVersionCheck: true
});The dangerouslySkipVersionCheck flag is only for migration or debugging. Never use in production.
Next steps
For complete documentation on toolkit versioning, including best practices and advanced configuration, see Toolkit versioning.