Troubleshooting
Connection Problems
Fix issues with external service connections — GitHub, FluentCRM, social media, and AI providers.
Understanding Connections
StorytellerOS connects to several external services. Each connection requires authentication that can expire or become invalid:
- AI providers — Anthropic, OpenAI, Gemini (one required)
- GitHub — Manuscript backup and version control (optional)
- Freepik — Image generation (optional)
- FluentCRM — Email marketing (optional)
- Direct2Readers — Direct sales (optional)
- Social accounts — Facebook, Instagram, etc. (optional)
Legacy Airtable accounts
Early-access users were on an Airtable-backed setup. Everyone has been migrated to the new hosted backend. If your wizard still asks for an Airtable Personal Access Token, or you see token-expired errors, your account hasn't been flipped yet — contact support and we'll handle it.
FluentCRM Connection Issues
Cannot Connect
- Verify your WordPress site is accessible
- Check that FluentCRM plugin is active
- Confirm the REST API is enabled on your site
- Verify your API credentials are correct
Finding Your Credentials
- Log in to your WordPress admin
- Go to FluentCRM settings
- Find the API or REST API section
- Copy your API key and secret
- Enter them in StorytellerOS Settings
Connection Times Out
- Your WordPress host may be blocking API requests
- Contact your host to whitelist StorytellerOS
- Check if security plugins are blocking the connection
Note
FluentCRM runs on your own WordPress site. Connection issues are often related to your hosting environment, not StorytellerOS.
Social Media Connection Issues
Account Disconnected
Social media connections expire periodically (usually 60-90 days):
- Go to Settings in StorytellerOS
- Find the disconnected account
- Click Reconnect
- Log in to the social platform
- Authorize StorytellerOS again
Platform-Specific Issues
Facebook / Instagram
- Must connect a Facebook Page, not personal profile
- Instagram must be a Business or Creator account
- Your Facebook and Instagram accounts must be linked
- Token expires every 60 days
Twitter / X
- Ensure your Twitter Developer account is active
- Check API access level
- Tokens can be revoked if you change your password
- Must authorize company page access separately
- Personal profile posting has different permissions
TikTok
- Requires a TikTok for Business account
- Content review may delay posts
Posts Failing After Connection
- Platform may have changed its API
- Your account may be restricted
- Content may violate platform guidelines
- Try disconnecting and reconnecting
Tip
Set a calendar reminder to check your social connections monthly. Reconnecting before expiration prevents failed scheduled posts.
GitHub Connection Issues
Cannot Connect
- Verify you have a GitHub account
- Check that you authorized StorytellerOS in GitHub settings
- Try disconnecting and reconnecting in Settings
Folder Creation Failed
When connecting GitHub, StorytellerOS creates folders for your content. If this fails:
- The connection still works — folders are created on first use
- You will see a warning during setup, but can continue
- Reconnecting GitHub in Settings will retry folder creation
Repository Access
- Ensure the selected repository exists and is accessible
- You need write access to the repository
- Private repositories work fine
Direct2Readers Connection Issues
Cannot Connect
- Verify you have a Direct2Readers account
- Check your API key is correct
- Ensure your account is in good standing
- Try regenerating your API key
Sales Not Syncing
- Sales data may take up to 24 hours to sync
- Check the last sync time in Settings
- Manual sync button available in Settings
- Verify products are linked correctly
AI Provider Connection Issues
OpenAI Issues
- Invalid key: Check for typos or extra spaces
- Quota exceeded: Add payment method or increase limit
- Rate limited: Wait a few minutes and try again
- Model unavailable: Try a different model
Anthropic Issues
- Invalid key: Regenerate in Anthropic console
- No credits: Add payment method
- Region restricted: Check if your region is supported
Freepik Issues
- Invalid key: Check API key in developer portal
- Plan limits: May have reached generation limit
- Content policy: Some prompts may be rejected
Testing Connections
Test each connection in Settings:
- Go to Settings
- Find the service you want to test
- Click Test Connection
- Wait for the result
What Success Looks Like
- Green checkmark or "Connected" status
- Last sync time shown
- Account name displayed
What Failure Looks Like
- Red X or "Disconnected" status
- Error message explaining the problem
- "Reconnect" button available
Common Error Messages
| Error | Meaning | Solution |
|---|---|---|
| 401 Unauthorized | Invalid or expired credentials | Update API key or reconnect |
| 403 Forbidden | No permission for this action | Check account permissions |
| 404 Not Found | Resource does not exist | Check IDs and URLs |
| 429 Too Many Requests | Rate limit exceeded | Wait and try again |
| 500 Server Error | External service issue | Try again later |
| Timeout | Request took too long | Check internet, try again |
Network Issues
Firewall Blocking Connections
- Corporate networks may block some APIs
- Try from a different network
- Contact IT to whitelist necessary domains
VPN Causing Issues
- Some services block VPN IP addresses
- Try disconnecting your VPN temporarily
- Use a different VPN server location
Best Practices
- Check connections regularly — Weekly check prevents surprises
- Keep backup credentials — Store API keys securely
- Do not share keys — Each user should have their own
- Rotate keys periodically — Regenerate every 6 months
- Monitor for expired connections — Watch for notification alerts
Need More Help?
If you cannot resolve your connection issue, our support team can help. Visit Contact Support to reach us.