Troubleshooting

Common issues and how to resolve them.

Authentication Issues

401 Unauthorized

Cause: Token is invalid, expired, or missing.

Fix:

# 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:

# 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:

  {"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

# Check current endpoint
teamday config get api_url

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

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

Command Not Found

# Verify installation
which teamday

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

Timeout Errors

For long-running operations:

# 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

Get Help

• Support: support@teamday.ai
• Community: Discord
• API Reference: /docs/api