Troubleshooting Guide

Common issues and solutions for the backend system.

Table of Contents

• API Issues
• Authentication & Authorization
• Publishing Failures
• Platform Integration Issues
• Cloud Functions Issues
• Firestore Issues
• Cloud Tasks Issues
• Credit System Issues
• Rate Limiting Issues
• Performance Issues

---

API Issues

Error: missing_api_key

Symptom: API returns 401 with missing_api_key error code

Causes:

• Missing X-API-Key header in request
• API key not configured in Firebase

Solutions:

# Check if API keys exist for user
firebase firestore:get users/USER_ID/apiKeys

# Create API key via Firebase console or admin script
# Key should be stored at: users/{uid}/apiKeys/{keyId}

Error: invalid_api_key

Symptom: API returns 401 with invalid_api_key error code

Causes:

• API key has been deleted or revoked
• API key belongs to different user
• API key format is incorrect

Solutions:

1. Verify API key exists in Firestore: users/{uid}/apiKeys/{keyId}
2. Check key hasn't expired or been revoked
3. Generate new API key for user

Error: missing_integrations

Symptom: API returns 400 with missing_integrations error code

Causes:

• User hasn't connected required platform(s)
• Integration was disconnected/revoked
• Platform is specified but not connected

Solutions:

1. Check user has connected the platform: users/\{uid\}/integrations/\{platform\}/\{accountId\}
2. Verify accessToken exists and hasn't been revoked
3. Have user reconnect the platform via OAuth flow

Prevention:

• Validate connected platforms before allowing post submission
• Implement UI to show connected vs. disconnected platforms
• Handle platform disconnections gracefully

Error: missing_account

Symptom: API returns 400 with missing_account error code

Message: "Multiple {platform} accounts connected. Please specify accountId."

Causes:

• User has multiple accounts for a platform
• Request didn't include required accountId parameter

Solutions:

// Include accountId in request
{
  "post": {
    "content": {
      "text": "Hello world",
      "platforms": ["instagram"]
    },
    "accounts": {
      "instagram": "ACCOUNT_ID_HERE"
    }
  }
}

Finding accountId:

# List all accounts for a platform
firebase firestore:get users/USER_ID/integrations/instagram
# Each document ID is an accountId

---

Authentication & Authorization

Firebase ID Token Expired

Symptom: Requests fail with "Token expired" or authentication errors

Causes:

• Firebase ID token has expired (1 hour lifetime)
• Client not refreshing token automatically

Solutions:

1. Implement automatic token refresh in client:

// Firebase SDK automatically refreshes tokens
firebase.auth().currentUser.getIdToken(true) // force refresh

2. Handle 401 responses by refreshing token and retrying

Insufficient Permissions

Symptom: Firestore operations fail with "Permission denied"

Causes:

• Firestore Security Rules blocking access
• User not authenticated
• Trying to access another user's data

Solutions:

1. Check Firestore Security Rules match your access patterns
2. Verify user is authenticated: firebase.auth().currentUser
3. Check document path matches user's UID

Debug Security Rules:

// Test rules in Firebase Console > Firestore > Rules > Simulator
// Or check function logs for permission errors

---

Publishing Failures

Post Stuck in orchestrating Status

Symptom: Post submission never completes, status stays orchestrating

Causes:

• Cloud Tasks queue doesn't exist
• Orchestrator function failed
• Network issues enqueuing tasks

Solutions:

1. Check orchestrator function logs:

firebase functions:log --only publishOrchestrator

2. Verify Cloud Tasks queues exist:

gcloud tasks queues list --location=us-central1

3. Check post submission document:

firebase firestore:get postSubmissions/SUBMISSION_ID
# Look for error field or targets array

Post Stuck in dispatched Status

Symptom: Post dispatched but individual platform runs never complete

Causes:

• Platform publish function failing
• Cloud Tasks queue paused
• Platform API issues

Solutions:

1. Check platform function logs:

firebase functions:log --only publishInstagram

2. Check run status:

firebase firestore:get postSubmissions/SUBMISSION_ID/runs/PLATFORM_ACCOUNTID
# Look for status and error fields

3. Check Cloud Tasks queue isn't paused:

gcloud tasks queues describe publish-instagram --location=us-central1

Platform Publish Fails with invalid_token

Symptom: Run status is failed with "Invalid token" or "Token expired" error

Causes:

• Platform access token expired
• Platform access token revoked by user
• OAuth refresh failed

Solutions:

1. Check token expiry:

firebase firestore:get users/USER_ID/integrations/PLATFORM/ACCOUNT_ID
# Check expiresAt field

2. Try refreshing token (if refreshToken exists):

# X and YouTube have refresh endpoints
# Call platform-specific refresh function

3. Have user reconnect platform if refresh fails

---

Platform Integration Issues

Facebook: No Pages Available

Symptom: Facebook OAuth completes but no pages are connected

Causes:

• User didn't grant page permissions
• User has no pages
• App doesn't have page access approved

Solutions:

1. Check app has page permissions approved in Facebook App Review
2. Use auth_type=rerequest to force permissions dialog
3. Verify user actually manages a page

Instagram: Container Creation Failed

Symptom: Instagram publish fails at container creation step

Causes:

• Media URL not publicly accessible
• Media format not supported
• Caption too long or contains invalid characters

Solutions:

1. Verify media URL is publicly accessible:

curl -I MEDIA_URL
# Should return 200 OK

2. Check media format:

   • Images: JPEG, PNG
   • Videos: MP4, MOV (H.264 codec)
   • Max size: 8MB images, 100MB videos

3. Validate caption:

   • Max 2,200 characters
   • Remove invalid characters

X: Media Upload Requires OAuth 1.0a

Symptom: X publish fails with x_media_requires_oauth1_or_mediaIds error

Causes:

• Trying to post media without OAuth 1.0a tokens
• X API v2 requires separate media upload

Solutions:

1. Complete OAuth 1.0a flow for media upload:

   • User must consent to OAuth 1.0a separately
   • Requires X_CONSUMER_KEY and X_CONSUMER_SECRET env vars

2. Or upload media separately and provide mediaIds:

{
  "post": {
    "content": {
      "text": "Check this out!",
      "platforms": ["x"],
      "mediaIds": ["MEDIA_ID_HERE"]
    }
  }
}

TikTok: Profile Fields Missing

Symptom: TikTok integration connected but profile incomplete

Causes:

• Missing required scopes
• TikTok API rate limiting
• User info endpoint failed

Solutions:

1. Ensure scopes include:

   • user.info.basic
   • user.info.profile

2. Check function logs for API errors:

firebase functions:log --only ttAuthCallback

3. Retry profile fetch via refresh endpoint

YouTube: Wrong Channel Connected

Symptom: User's brand account channel not showing

Causes:

• User has multiple channels (personal + brand)
• OAuth returns default channel only
• Channel selection not implemented

Solutions:

1. Use prompt=select_account in OAuth URL to force channel selection
2. Implement channel picker if multiple channels detected
3. Check extra.channel field for full channel data

---

Cloud Functions Issues

Function Deployment Fails

Symptom: firebase deploy --only functions fails

Common errors:

"Billing must be enabled":

• Solution: Upgrade to Blaze plan in Firebase Console

"Function size exceeds 100MB":

• Solution: Remove unnecessary dependencies, check node_modules size
• Exclude dev dependencies from deployment

"Deployment timeout":

• Solution: Deploy functions individually: firebase deploy --only functions:api
• Check network connectivity
• Retry deployment

Function Crashes on Startup

Symptom: Function deploys but immediately fails on invocation

Causes:

• Missing environment variables
• Syntax errors in code
• Dependency issues

Solutions:

1. Check function logs immediately after deployment:

firebase functions:log --only FUNCTION_NAME

2. Verify all environment variables are set:

firebase functions:config:get

3. Test function locally:

cd apps/functions
npm run dev
# Test endpoints locally

Function Timeout

Symptom: Function exceeds time limit (60s default, 540s max)

Causes:

• Long-running operations
• Waiting for external API calls
• Inefficient queries

Solutions:

1. Increase timeout in firebase.json:

{
  "functions": [
    {
      "source": "apps/functions",
      "codebase": "functions",
      "runtime": "nodejs22",
      "timeoutSeconds": 300
    }
  ]
}

2. Optimize slow operations:

   • Use Cloud Tasks for async work
   • Batch Firestore operations
   • Add timeouts to external API calls

3. Check function logs for slow operations

Function Cold Start Latency

Symptom: First request to function takes 3-5 seconds

Causes:

• Function not kept warm
• Large function size
• Many dependencies

Solutions:

1. Enable minimum instances (costs more):

{
  "functions": [
    {
      "source": "apps/functions",
      "minInstances": 1
    }
  ]
}

2. Reduce function size:

   • Split large functions
   • Remove unused dependencies
   • Use dynamic imports

3. Implement keep-alive ping (not recommended, wastes invocations)

---

Firestore Issues

Index Not Found

Symptom: Query fails with "Index not found" error

Causes:

• Composite index not created
• Index still building
• Query doesn't match any index

Solutions:

1. Deploy indexes:

firebase deploy --only firestore:indexes

2. Check index status:

firebase firestore:indexes
# Wait for "READY" status

3. Follow error message link to create index automatically

Document Too Large

Symptom: Write fails with "Document size exceeds 1MB"

Causes:

• Storing large arrays or nested data
• Accumulated data over time

Solutions:

1. Split data into subcollections:

// Instead of large array in document
users/\{uid\}/integrations/\{platform\}/\{accountId\}

// Use subcollection
users/\{uid\}/posts/\{postId\}/runs/\{platform\}

2. Use Cloud Storage for large data (media, files)

3. Paginate large arrays

Write Conflicts / Transaction Failures

Symptom: Transactions fail with "Transaction failed" or "Contention" errors

Causes:

• Multiple writes to same document
• High concurrency
• Long-running transactions

Solutions:

1. Reduce transaction scope
2. Use batched writes instead of transactions when possible
3. Implement retry logic with exponential backoff
4. Consider distributed counters for high-traffic documents

---

Cloud Tasks Issues

Tasks Not Being Dispatched

Symptom: Tasks enqueued but never execute

Causes:

• Queue is paused
• Queue doesn't exist
• Function URL incorrect
• Authentication issues

Solutions:

1. Check queue status:

gcloud tasks queues describe QUEUE_NAME --location=us-central1

2. Resume paused queue:

gcloud tasks queues resume QUEUE_NAME --location=us-central1

3. Verify function URL is accessible:

curl -X POST FUNCTION_URL
# Should return 401 (unauthorized) not 404

Tasks Failing with 401 Unauthorized

Symptom: Tasks repeatedly fail with 401 error

Causes:

• Function requires authentication
• Service account doesn't have permissions

Solutions:

1. If functions should be public, remove auth requirement
2. Add OIDC token to task:

const task = {
  httpRequest: {
    url: functionUrl,
    httpMethod: 'POST',
    body: Buffer.from(JSON.stringify(payload)).toString('base64'),
    oidcToken: {
      serviceAccountEmail: 'SERVICE_ACCOUNT_EMAIL'
    }
  }
};

3. Grant Cloud Functions Invoker role to service account

Tasks Retrying Forever

Symptom: Tasks keep retrying and never succeed

Causes:

• Function returns 5xx error (retriable)
• Infinite loop in retry logic
• No max attempts configured

Solutions:

1. Configure max attempts on queue:

gcloud tasks queues update QUEUE_NAME \
  --max-attempts=5 \
  --location=us-central1

2. Fix function to return 4xx (non-retriable) for permanent failures

3. Implement exponential backoff:

gcloud tasks queues update QUEUE_NAME \
  --min-backoff=10s \
  --max-backoff=600s \
  --location=us-central1

---

Credit System Issues

Credits Not Deducted

Symptom: AI operation completes but credits remain unchanged

Causes:

• Credit consumption logic not called
• Transaction failed
• Function crashed before credit update

Solutions:

1. Check function logs for credit deduction:

firebase functions:log | grep "credits"

2. Verify credit transaction was created:

firebase firestore:get users/USER_ID/creditTransactions
# Look for recent transaction

3. Manually adjust credits if necessary:

firebase firestore:update users/USER_ID '{"credits": 50}'

Insufficient Credits Error But User Has Credits

Symptom: User gets insufficient_credits error despite having credits

Causes:

• Race condition (multiple requests)
• Stale credit balance
• Cache issue

Solutions:

1. Check actual credit balance:

firebase firestore:get users/USER_ID
# Look at credits field

2. Check for concurrent operations:

firebase firestore:get users/USER_ID/creditTransactions --limit=10
# Look for multiple rapid transactions

3. Implement proper transaction isolation in credit operations

---

Rate Limiting Issues

User Hit Rate Limit Unexpectedly

Symptom: User gets 429 error but hasn't made many requests

Causes:

• Old requests still in sliding window
• Rate limit window duration shorter than expected
• Multiple devices/sessions

Solutions:

1. Check rate limit document:

firebase firestore:get rateLimits/rateLimit:USER_ID:/v1/posts
# Look at window array timestamps

2. Explain sliding window to user:

   • Free: 5 requests per 15 minutes
   • Pro: 10 requests per 1 minute

3. User can wait for oldest request to age out (check X-RateLimit-Reset header)

Rate Limit Not Working

Symptom: User exceeds rate limit but not blocked

Causes:

• Rate limit middleware not applied
• Staff member (has higher limits)
• Rate limit document not found/created

Solutions:

1. Verify rate limit middleware is active on endpoint
2. Check if user is staff:

firebase firestore:get users/USER_ID
# Look for isStaff: true

3. Check rate limit document exists after first request

---

Performance Issues

Slow API Response Times

Symptom: API requests take >2 seconds

Causes:

• Cold start latency
• Slow Firestore queries
• External API calls blocking
• Unoptimized code

Solutions:

1. Check function execution time in logs:

firebase functions:log --only api
# Look for execution time

2. Optimize Firestore queries:

   • Add indexes
   • Reduce document reads
   • Use limit() on queries

3. Move slow operations to Cloud Tasks (async)

4. Cache frequently accessed data

High Firestore Read/Write Costs

Symptom: Unexpected Firebase bill

Causes:

• Inefficient queries
• Reading large documents
• High traffic
• Missing indexes (full collection scans)

Solutions:

1. Review Firestore usage in console

2. Identify expensive queries:

   • Use Firestore query profiler
   • Check for missing indexes

3. Optimize data model:

   • Denormalize for read efficiency
   • Use subcollections
   • Implement pagination

4. Add caching layer (carefully, can cause stale data)

Function Memory Exceeded

Symptom: Function crashes with "Memory limit exceeded"

Causes:

• Large media processing
• Memory leaks
• Too many concurrent operations

Solutions:

1. Increase memory allocation:

{
  "functions": [
    {
      "source": "apps/functions",
      "memory": 1024
    }
  ]
}

2. Process large files in chunks
3. Clean up resources (close connections, clear buffers)
4. Use Cloud Storage for large files instead of memory

---

Debugging Tools

View Function Logs

# All logs
firebase functions:log

# Specific function
firebase functions:log --only functionName

# Follow logs in real-time
firebase functions:log --only functionName --follow

# Filter by severity
firebase functions:log --only functionName | grep ERROR

Query Firestore

# Get specific document
firebase firestore:get users/USER_ID

# Get collection
firebase firestore:get users

# Run query
# (Use Firebase Console > Firestore > Query)

Test Cloud Tasks

# List tasks in queue
gcloud tasks list --queue=QUEUE_NAME --location=us-central1

# Delete specific task
gcloud tasks delete TASK_ID --queue=QUEUE_NAME --location=us-central1

# Purge all tasks in queue
gcloud tasks queues purge QUEUE_NAME --location=us-central1

Check Platform API Status

• Facebook: https://developers.facebook.com/status
• Instagram: https://developers.facebook.com/status (same as Facebook)
• X: https://api.twitterstat.us
• TikTok: https://developers.tiktok.com/
• YouTube: https://www.google status.com/dashboard (Google APIs)

---

Getting Help

Check Documentation

• Orchestration
• API Reference
• Deployment Checklist
• Tracing & Logging

Enable Debug Logging

Set DEBUG environment variable in functions:

firebase functions:config:set debug.enabled=true

Contact Support

When reporting issues, include:

• Error message and code
• Function logs (sanitized)
• Steps to reproduce
• Environment (staging/production)
• Affected user ID (if applicable)
• Timestamp of issue

Community Resources

• Firebase Documentation: https://firebase.google.com/docs
• Firebase Support: https://firebase.google.com/support
• Stack Overflow: Tag questions with firebase and specific service