Instance Won't Start - Common Causes

Overview

If your instance fails to start or gets stuck in "Starting" status, this guide will help you diagnose and fix the problem.

Quick Checklist

Before diving into detailed troubleshooting, verify:

• ✓ Your subscription is active (check billing status)
• ✓ Payment method is valid (no failed charges)
• ✓ Instance status shows "Starting" or "Error"
• ✓ You've waited at least 2 minutes (startup can take 60-120 seconds)

Common Causes

1. Invalid or Missing API Keys

Symptoms:

• Instance starts then immediately stops
• Logs show authentication errors
• Error messages mention "invalid API key" or "unauthorized"

Solutions:

1. Go to your instance configuration
2. Verify environment variables are set correctly:
   • OPENAI_API_KEY starts with sk-
   • ANTHROPIC_API_KEY starts with sk-ant-
   • TELEGRAM_BOT_TOKEN format is correct
3. Check for extra spaces or hidden characters
4. Verify keys haven't been revoked
5. Test keys directly on provider's website
6. Update keys and restart instance

2. Insufficient API Credits or Quota

Symptoms:

• Instance starts but AI doesn't respond
• Logs show "quota exceeded" or "insufficient funds"

Solutions:

1. Check your AI provider dashboard:
   • OpenAI: platform.openai.com/account/billing
   • Anthropic: console.anthropic.com/settings/billing
2. Add payment method or increase usage limit
3. Wait for quota reset (if using free tier)
4. Restart instance after resolving

3. Telegram/Discord Bot Token Issues

Symptoms:

• Instance starts but bot doesn't respond
• Logs show "bot token invalid"

Solutions:

For Telegram:

1. Message @BotFather on Telegram
2. Send /mybots
3. Select your bot
4. Verify bot is not deleted or revoked
5. Get a new token if needed (/token)
6. Update TELEGRAM_BOT_TOKEN in AgentClaw

For Discord:

1. Go to Discord Developer Portal
2. Select your application
3. Go to "Bot" section
4. Verify bot token is correct
5. Regenerate token if compromised
6. Update DISCORD_BOT_TOKEN

4. Subscription or Payment Issues

Symptoms:

• Can't start instance at all
• Error message about subscription

Solutions:

1. Check your subscription status in dashboard
2. Verify payment method in Stripe portal
3. Look for failed payment emails
4. Update payment method if needed
5. Contact support if subscription shows active but instance won't start

5. Configuration Errors

Symptoms:

• Instance starts then crashes immediately
• Logs show configuration errors

Solutions:

1. Review all environment variables for typos
2. Check for conflicting settings
3. Remove any custom variables you added
4. Try with minimal configuration (only required vars)
5. Restart instance after changes

6. OpenClaw Version Issues

Symptoms:

• Instance won't start after version update
• Logs show compatibility errors

Solutions:

1. Try reverting to previous OpenClaw version
2. Check OpenClaw release notes for breaking changes
3. Update environment variables for new version
4. Contact support if issue persists

Reading Logs for Diagnosis

Logs are your best friend for troubleshooting. To access logs:

1. Go to your instance details page
2. Click the "Logs" tab
3. Look for ERROR or WARNING messages
4. Note the timestamp of failures

Common error patterns:

• "invalid API key" → Check AI provider keys
• "401 Unauthorized" → API authentication failed
• "quota exceeded" → Hit usage limits
• "bot token invalid" → Check messaging platform tokens
• "connection refused" → Network or configuration issue

Learn more about reading and interpreting logs.

Step-by-Step Troubleshooting

If the quick fixes above don't work, follow this systematic approach:

Step 1: Check Status and Logs

1. Note the current instance status
2. Read the latest logs
3. Screenshot any error messages

Step 2: Verify Configuration

1. List all environment variables
2. Check each value is correct (no typos)
3. Verify required variables are present

Step 3: Test Components Individually

1. Test API keys on provider websites
2. Test bot tokens with test messages
3. Verify payment method is active

Step 4: Try Minimal Configuration

1. Remove all optional environment variables
2. Keep only required ones
3. Restart and test
4. Add variables back one at a time

Step 5: Contact Support

If still not working, email support@agentclaw.app with:

• Instance name and subdomain
• Screenshot of error from logs
• Description of what you tried
• Timestamp of the issue

Preventing Future Issues

• Set up billing alerts: Get notified before hitting limits
• Keep API keys secure: Never share or commit to code
• Monitor regularly: Check logs weekly for warnings
• Test after changes: Always test after updating config
• Document your setup: Keep notes on your configuration

When to Contact Support

Contact support immediately if:

• Instance won't start despite correct configuration
• Logs show internal server errors
• Problem started without any changes on your end
• You see unexpected charges or subscription issues
• Multiple instances are affected

Next Steps

• Learn about reading real-time logs
• Understand API key authentication errors
• Read about connection issues
• Review adding API keys securely