# Troubleshooting

Common issues and solutions when working with TeamDay agents, Spaces, MCPs, and the API.

# Troubleshooting

Common issues and how to resolve them.

---

## Authentication Issues

### 401 Unauthorized

**Cause:** Token is invalid, expired, or missing.

**Fix:**
```bash
# Check auth status
teamday auth status

# Refresh expired OAuth token
teamday auth refresh

# Re-authenticate if refresh fails
teamday auth login

# Or set a new PAT
teamday auth set-key "td_your_new_token"
```

### 403 Forbidden

**Cause:** You don't have access to the resource (wrong organization, or resource belongs to another user).

**Fix:**
- Verify you're in the correct organization: `teamday auth status`
- Check that the resource belongs to your org
- For organization-level actions, ensure your role has the necessary permissions

---

## Agent Execution Issues

### 501 Execution Error

**Cause:** No Claude API credential is configured.

**Fix:**
```bash
# Check credential status
teamday keys status

# Set your Claude OAuth token
teamday keys set oauth sk-ant-oat01-your-token

# Or set an Anthropic API key
teamday keys set api-key sk-ant-api03-your-key
```

### Agent Doesn't Respond

**Possible causes:**
- The conversation timed out (default: 5 minutes for API calls)
- The agent is stuck in a tool loop
- The Space is unreachable

**Fix:**
- Try a new conversation
- Simplify your request
- Check if the Space still exists: `teamday spaces get <id>`

### Agent Can't Find Files

**Cause:** The agent is looking in the wrong directory, or files haven't been synced.

**Fix:**
- Verify files exist: `teamday spaces ls <space-id> /`
- For Git Spaces: `teamday spaces git <space-id> pull`
- Check that the file path is correct (paths are relative to the Space root)

---

## MCP Issues

### MCP Tools Not Available

**Cause:** MCP server failed to start, or isn't installed on the Space.

**Fix:**
1. Verify the MCP is installed: `teamday spaces get <space-id>`
2. Start a **new** conversation (MCPs load at conversation start)
3. Check that required secrets are configured

### OAuth MCP Expired

**Cause:** The OAuth token for an integration (e.g., Google Analytics) has expired.

**Fix:**
- Reconnect via Space settings in the web app
- Or the agent can request re-authentication:
  ```json
  {"action": "requestReauth", "target": "google-analytics"}
  ```

### MCP Server Crashes

**Cause:** Missing dependencies, wrong command, or invalid configuration.

**Fix:**
- Test the MCP command manually: `npx -y @package/name --help`
- Verify environment variables are set as Space secrets
- Check the MCP configuration in `.mcp.json`

---

## Space Issues

### Can't Create Space

**Cause:** You've reached your plan's Space limit.

**Fix:**
- Archive unused Spaces: `teamday spaces delete <id>`
- Upgrade your plan for more Space slots

### Files Not Persisting

**Cause:** Files created during a conversation are stored in the sandbox. If the sandbox is recreated, files may be lost.

**Fix:**
- For important files, commit to Git
- Use the `teamday spaces ls` command to verify file existence
- Critical data should be stored in external services, not just the filesystem

---

## CLI Issues

### Cannot Connect to API

```bash
# Check current endpoint
teamday config get api_url

# Fix if wrong
teamday config set api_url https://cc.teamday.ai

# Test with override
teamday --api-url https://cc.teamday.ai agents list
```

### Command Not Found

```bash
# Verify installation
which teamday

# Re-link if needed
cd /path/to/teamday/packages/cli
bun link
```

### Timeout Errors

For long-running operations:

```bash
# Increase timeout (default: 300000ms = 5 minutes)
teamday config set timeout 600000

# Or per-command
teamday agents exec <id> "long task" --timeout 600000
```

---

## Common Error Codes

| Code | Meaning | Common Fix |
|------|---------|-----------|
| 400 | Bad Request | Check request body, required fields |
| 401 | Unauthorized | Refresh token or re-authenticate |
| 403 | Forbidden | Wrong org or insufficient permissions |
| 404 | Not Found | Resource doesn't exist or was deleted |
| 429 | Rate Limited | Wait and retry, or use your own API key |
| 500 | Server Error | Retry, or contact support |
| 501 | No Credential | Set Claude API credential via `teamday keys set` |

---

## Get Help

- **Support:** support at teamday.ai
- **Community:** [Discord](https://discord.com/invite/DbUyE6b4t5)
- **API Reference:** [/docs/api](https://docs.teamday.ai/api)