Troubleshooting — Getting Started

Common issues and how to fix them.

Authentication

”Unauthorized” or 401 errors

• Check your token: Workspace tokens start with mwt_. Project API keys start with ask_. Make sure you’re using the right one.
• Token expired: Workspace tokens don’t expire, but project auth tokens do. Re-authenticate with aerostack login.
• Wrong workspace: Verify the workspace slug matches the token. A token from workspace “acme-dev” won’t work for “acme-prod”.

”Forbidden” or 403 errors

• Plan limits: You may have hit your plan’s rate or resource limits. Check your billing dashboard.
• Tool permissions: If using agent automation, check that the tool is enabled for your workspace.

CLI Issues

aerostack: command not found

# Reinstall
curl -fsSL https://get.aerostack.dev | sh

# Or use npx (no install needed)
npx @aerostack/cli init my-project

aerostack login hangs

• Check your internet connection
• Try with --verbose flag: aerostack login --verbose
• If behind a corporate proxy, set HTTPS_PROXY environment variable

aerostack dev fails to start

• Make sure port 8787 is not in use: lsof -i :8787
• Check that wrangler.toml (or aerostack.toml) exists in your project root
• Run npm install to ensure dependencies are installed

SDK Integrations

getTools() returns empty tools array

• Verify your workspace has MCP servers connected (check the dashboard)
• Check that the MCP servers are deployed and active (not paused)
• Ensure your workspace token has access to the connected servers

Tool calls fail with “tool not found”

• The tool may have been removed from the workspace since you fetched tools. Call getTools() again.
• For @aerostack/sdk-openai: tool names are sanitized to fit OpenAI’s 64-character limit. The SDK handles this automatically — don’t manually map names.

TypeScript errors with SDK imports

# Make sure you have the latest version
npm install @aerostack/sdk-vercel-ai@latest
npm install @aerostack/sdk-langchain@latest
npm install @aerostack/sdk-openai@latest

MCP Servers

”MCP server not responding”

• Check server status in your MCP dashboard
• Hosted MCPs may take 10-30 seconds on first cold start
• Proxied MCPs depend on the upstream service being available

Secrets not working

• Secrets are encrypted and injected at runtime. They don’t appear in logs.
• Verify the secret name matches exactly (case-sensitive)
• After updating a secret, the MCP server may need a fresh invocation to pick it up

Bots

Bot not responding to messages

1. Check the webhook is registered: look for a green “Active” status in your bot settings
2. Verify the platform token is correct (e.g., Telegram BotFather token)
3. Check the bot’s conversation logs in the dashboard for errors
4. Ensure the bot’s workspace has the required MCP tools connected

Bot responds but tools don’t work

• The bot’s workspace must have the relevant MCP servers connected
• Check that tool permissions allow the bot to use those tools
• Look at the workflow execution log for error details

Deployments

Deploy fails with “worker size exceeded”

• Cloudflare Workers have a 10MB limit after compression
• Remove unused dependencies from your function
• Split large functions into smaller, focused ones

Changes not reflecting after deploy

• Allow 30-60 seconds for edge propagation
• Clear your browser cache or test with curl
• Check that you deployed to the right environment (dev vs prod)

Still Stuck?

• Ask in our Discord community — we respond fast
• Use the AI Assistant to debug issues
• Email us: hello@aerostack.dev