# Troubleshooting — Getting Started

> Fix common Aerostack issues — auth errors, deployment failures, database connection problems, and WebSocket drops. Step-by-step debugging guide.

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](https://app.aerostack.dev/settings/billing).
- **Tool permissions**: If using agent automation, check that the tool is enabled for your workspace.

## CLI Issues

### `aerostack: command not found`

```bash
# 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](https://app.aerostack.dev/workspaces))
- 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

```bash
# 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](https://app.aerostack.dev/mcp)
- 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](https://discord.gg/aerostack) — we respond fast
- Use the [AI Assistant](https://app.aerostack.dev/assistant) to debug issues
- Email us: hello@aerostack.dev