Troubleshooting Guide

This guide covers common issues you might encounter while using CrossPostr and their solutions.

Quick Diagnostics

Before diving into specific issues, try these quick fixes:

1. Refresh the page - Clears temporary state issues
2. Clear browser cache - Resolves cached data problems
3. Check your internet connection - Ensures API connectivity
4. Verify API keys - Confirms platform integrations are working
5. Check platform status - Visit status pages for outages

Authentication Issues

Cannot Sign In

Symptoms:

• "Invalid credentials" errors
• Redirect loops
• Blank sign-in page

Solutions:

1. Clear browser data:

   # Chrome: Settings > Privacy > Clear browsing data
   # Firefox: Settings > Privacy > Clear Data
   # Safari: Develop > Empty Caches

2. Check email verification:

   • Look for verification email in spam folder
   • Request new verification link
   • Use different email provider if issues persist

3. Try different sign-in method:

   • If email fails, try Google or GitHub
   • If OAuth fails, try email/password

4. Disable browser extensions:

   • Ad blockers can interfere with authentication
   • Privacy extensions may block OAuth redirects

Account Access Issues

Problem: Can't access account after signing in Solution: Check if your account needs admin approval (enterprise users)

Problem: OAuth redirect errors Solution: Ensure you're using the correct domain (crosspostr.app, not localhost)

AI Credits & Usage

Credits Not Updating

Symptoms:

• Credit balance shows incorrect amount
• Credits don't deduct after AI usage
• "Insufficient credits" error with available balance

Solutions:

1. Refresh credit balance:

   // In browser console
   localStorage.removeItem("ai-credits-cache");
   location.reload();

2. Check tier limitations:

   • Free tier: 100 credits/month
   • Pro tier: 1,000 credits/month
   • Business tier: 5,000 credits/month

3. Verify usage tracking:

   • Go to Dashboard → Settings → AI Credits
   • Check usage history
   • Look for failed operations

AI Features Not Working

Problem: AI assistant doesn't respond Diagnosis:

# Check if AI service is available
curl -X POST https://api.crosspostr.app/v1/ai/health

Solutions:

1. Check your credit balance
2. Verify network connectivity
3. Try refreshing the page
4. Contact support if issue persists

Problem: Poor AI response quality Solutions:

1. Be more specific in prompts
2. Provide more context
3. Try breaking down complex requests
4. Use examples in your prompts

Publishing Errors

Dev.to Publishing Failures

Error: 401 Unauthorized Solution:

1. Check API key validity at dev.to/settings/extensions
2. Regenerate API key if expired
3. Update key in CrossPostr settings

Error: 422 Unprocessable Entity Common causes:

• Title too long (max 100 characters)
• Too many tags (max 4)
• Invalid markdown syntax
• Duplicate content

Solutions:

# Check title length

Title: "Understanding React Hooks" ✓ (25 chars)
Title: "Complete Comprehensive Ultimate Advanced Guide to Understanding React Hooks and State Management" ✗ (105 chars)

# Check tag count

Tags: react, javascript, tutorial, beginners ✓ (4 tags)
Tags: react, javascript, tutorial, beginners, webdev ✗ (5 tags)

Hashnode Publishing Failures

Error: Invalid publication slug Solution:

1. Verify publication slug in Hashnode settings
2. Ensure you have write permissions
3. Check if publication is active

Error: Content validation failed Solutions:

1. Remove unsupported HTML tags
2. Check image URLs are accessible
3. Ensure canonical URLs are valid

General Publishing Issues

Problem: Articles appear on wrong publication Solution: Check platform-specific settings in publish dialog

Problem: Formatting looks different on platforms Solutions:

1. Use platform preview before publishing
2. Stick to common markdown features
3. Test with simple formatting first

Content Editor Issues

Editor Not Loading

Symptoms:

• Blank editor area
• Infinite loading spinner
• Console errors

Solutions:

1. Check JavaScript console:

   # Open browser console (F12)
   # Look for error messages
   # Common errors and fixes:

2. Browser compatibility:

   • Chrome 90+ ✓
   • Firefox 88+ ✓
   • Safari 14+ ✓
   • Edge 90+ ✓

3. Disable conflicting extensions:

   • Grammarly (can interfere with editor)
   • Ad blockers (may block editor scripts)
   • Content modifiers (change page behavior)

Content Not Saving

Problem: Draft doesn't save automatically Solutions:

1. Check internet connection
2. Verify you're signed in
3. Try manual save (Ctrl+S)
4. Copy content to clipboard as backup

Problem: Content lost after page refresh Prevention:

// Enable auto-save in settings
// Backup important content regularly
// Use external editor for long articles

Performance Issues

Slow Loading Times

Causes & Solutions:

1. Large images:

   # Optimize images before upload
   
   - Use WebP format when possible
   - Compress images to < 1MB
   - Resize to appropriate dimensions

2. Too many browser tabs:

   • Close unused tabs
   • Restart browser
   • Clear cache and cookies

3. Slow internet connection:

   • Check connection speed
   • Use mobile hotspot as backup
   • Contact ISP if persistent

High Memory Usage

Symptoms:

• Browser becomes unresponsive
• Tab crashes frequently
• Computer fans running high

Solutions:

1. Close other applications
2. Restart browser
3. Use private/incognito mode
4. Update browser to latest version

Analytics Issues

Missing Analytics Data

Problem: No views/engagement data showing Checks:

1. Verify platform API keys are correct
2. Ensure articles are published (not drafts)
3. Check if platforms have updated their APIs
4. Wait 24-48 hours for data to sync

Problem: Inconsistent data across platforms Explanation:

• Each platform counts metrics differently
• Some platforms have delayed reporting
• CrossPostr shows aggregated best-effort data

Analytics Not Updating

Solution:

// Force refresh analytics data
// Go to Dashboard → Analytics
// Click "Refresh Data" button
// Or wait for next scheduled sync (every 6 hours)

Integration Issues

Platform API Errors

Dev.to API Issues:

# Test API connectivity
curl -H "api-key: YOUR_KEY" https://dev.to/api/articles/me

# Common responses:
# 200: Success
# 401: Invalid API key
# 429: Rate limited
# 500: Dev.to server error

Hashnode API Issues:

# Test GraphQL endpoint
curl -X POST https://api.hashnode.com/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { me { username } }"}'

Webhook Failures

Problem: Not receiving webhook notifications Diagnosis:

1. Check webhook URL is accessible
2. Verify endpoint responds with 200 status
3. Check webhook secret matches

Testing webhooks locally:

# Use ngrok for local testing
npm install -g ngrok
ngrok http 3000

# Use the ngrok URL as webhook endpoint

Mobile App Issues

App Won't Start

Solutions:

1. Force close and restart app
2. Update to latest version
3. Restart device
4. Clear app cache/data

Sync Issues

Problem: Changes not syncing between devices Solutions:

1. Check internet connection on both devices
2. Force sync in app settings
3. Sign out and sign back in
4. Contact support for account sync issues

Error Codes Reference

HTTP Status Codes

| Code | Meaning | Common Cause | Solution | | ---- | ------------ | ------------------------ | -------------------- | | 400 | Bad Request | Invalid input data | Check request format | | 401 | Unauthorized | Invalid API key | Update credentials | | 403 | Forbidden | Insufficient permissions | Check account tier | | 404 | Not Found | Resource doesn't exist | Verify URL/ID | | 429 | Rate Limited | Too many requests | Wait and retry | | 500 | Server Error | CrossPostr issue | Contact support |

CrossPostr Error Codes

| Code | Description | Solution | | ----- | ------------------------- | ------------------------------ | | CP001 | AI credits exhausted | Upgrade plan or wait for reset | | CP002 | Content validation failed | Check content format | | CP003 | Platform API error | Check platform status | | CP004 | Authentication required | Sign in again | | CP005 | Feature not available | Check subscription tier |

Browser-Specific Issues

Chrome Issues

Problem: Extensions interfering with editor Solution: Use incognito mode to test

Problem: Memory leaks with long sessions Solution: Restart browser periodically

Firefox Issues

Problem: WebRTC connections failing Solution: Enable WebRTC in about:config

Safari Issues

Problem: Clipboard API not working Solution: Grant clipboard permissions in preferences

Getting Additional Help

Before Contacting Support

1. Check status page: status.crosspostr.app
2. Search documentation: Use the search function
3. Try incognito mode: Rules out browser-specific issues
4. Test with different account: Isolates account-specific problems

Providing Useful Information

When contacting support, include:

Subject: [Issue Type] Brief description

Environment:
- Browser: Chrome 91.0.4472.124
- OS: macOS 12.5
- Account: your-email@example.com
- Time: 2025-06-15 14:30 UTC

Steps to reproduce:
1. Go to Dashboard
2. Click "New Article"
3. Type content
4. Click "Save"

Expected result: Article saves successfully
Actual result: Error message "Failed to save"

Console errors: [paste any error messages]
Screenshots: [attach if helpful]

Support Channels

1. Email: support@crosspostr.app

   • Best for: Account issues, billing, bugs
   • Response time: 24 hours

2. Discord: discord.gg/crosspostr

   • Best for: Quick questions, community help
   • Response time: Usually within hours

3. GitHub Issues: github.com/crosspostr/platform

   • Best for: Bug reports, feature requests
   • Response time: 2-3 business days

4. Knowledge Base: help.crosspostr.app

   • Best for: Self-service troubleshooting
   • Available 24/7

Emergency Support

For critical issues affecting business operations:

• Email: urgent@crosspostr.app
• Phone: Available for Enterprise customers
• Status Updates: Follow @CrossPostrStatus

---

Still need help? Our support team is here to assist you. Don't hesitate to reach out!

Last updated: June 15, 2025