Connection Problems

Understanding Connections

StorytellerOS connects to several external services. Each connection requires authentication that can expire or become invalid:

• Airtable — Stores all your data
• GitHub — Manuscript backup and version control (optional)
• FluentCRM — Email marketing (optional)
• Direct2Readers — Direct sales (optional)
• Social accounts — Facebook, Instagram, etc. (optional)
• AI providers — OpenAI, Anthropic, Freepik (optional)

Airtable Connection Issues

Token Expired

Airtable Personal Access Tokens can expire based on your settings:

1. Log in to airtable.com
2. Go to your account settings
3. Find Personal Access Tokens
4. Check if your token is still active
5. Generate a new token if needed
6. Update the token in StorytellerOS Settings

Wrong Base ID

If StorytellerOS cannot find your data:

• Verify the Base ID in Settings matches your Airtable base
• Find your Base ID in Airtable by opening the base and looking at the URL
• The Base ID starts with "app" followed by characters

Permission Issues

Your token needs these permissions:

• Read/write access to the base
• Schema access (to check table structure)

"All Bases" Tokens May Fail Validation

Due to an Airtable API limitation, Personal Access Tokens configured with"All current and future bases" access may fail permission checks even when all required scopes are enabled.

If you are experiencing permission errors with an "all bases" token:

1. Go to airtable.com/create/tokens
2. Create a new Personal Access Token
3. Select your specific base from the dropdown
4. Add all required scopes (data.records:read, data.records:write, schema.bases:read, schema.bases:write)
5. Update the token in StorytellerOS Settings

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

1. Log in to your WordPress admin
2. Go to FluentCRM settings
3. Find the API or REST API section
4. Copy your API key and secret
5. 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

Social Media Connection Issues

Account Disconnected

Social media connections expire periodically (usually 60-90 days):

1. Go to Settings in StorytellerOS
2. Find the disconnected account
3. Click Reconnect
4. Log in to the social platform
5. 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

LinkedIn

• 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

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

1. Verify you have a Direct2Readers account
2. Check your API key is correct
3. Ensure your account is in good standing
4. 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:

1. Go to Settings
2. Find the service you want to test
3. Click Test Connection
4. 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

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