Codeless Sync LogoCodeless Sync

Troubleshooting

Solutions to common issues and errors in Codeless Sync.

Updated: 28 Oct 2025

Troubleshooting

Find solutions to common issues you may encounter while using Codeless Sync.

Connection Issues

Database Connection Failed

Symptoms: Cannot connect to your PostgreSQL database

Solutions:

  1. Verify your connection string

    • Check that your connection string is correct and complete
    • Ensure the password is included and correct
    • Verify the host, port, and database name are accurate
    • See the Database Setup Guide for help finding your credentials

  2. Check database status

    • Ensure your database is active (not paused)
    • Verify you have network connectivity
    • Check your provider's status page for outages

  3. Test your connection

    • Use CLS's "Test Connection" button in the project form
    • Verify SSL is enabled on your database

Provider API Key Invalid

Symptoms: API key validation fails

Solutions:

  1. Verify the key format

    • Restricted keys (recommended): rk_test_ (test) or rk_live_ (production)
    • Secret keys (fallback): sk_test_ (test) or sk_live_ (production)
    • Ensure you copied the entire key

  2. Check provider dashboard

    • Go to your provider's API keys section
    • Verify the key exists and is active
    • Check that it hasn't been revoked

  3. Try generating a new key

    • Create a fresh API key in your provider dashboard
    • Update your Codeless Sync (CLS) configuration
    • Delete the old key

Sync Issues

Sync Fails Immediately

Symptoms: Sync status shows "failed" right after starting

Common Causes:

  1. Invalid API credentials

    • Re-test your provider API key
    • Verify database connection

  2. Table not found

    • Confirm table exists in your database
    • Check table name matches exactly
    • Verify table is in the public schema

  3. Permission errors

    • Ensure database user has write permissions
    • Check table policies allow inserts/updates

Fix:

-- Verify table exists
SELECT * FROM information_schema.tables
WHERE table_name = 'your_table_name';

-- Check table structure
\\d your_table_name

Sync Stuck at 0%

Symptoms: Sync starts but progress never increases

Solutions:

  1. Check sync history

    • Look for error messages
    • Review detailed logs

  2. Verify data exists

    • Ensure you have data in your provider account
    • Check filters if using any

  3. Wait longer

    • First syncs may take time to start
    • Allow 2-3 minutes before troubleshooting

  4. Cancel and retry

    • Cancel the stuck sync
    • Wait 1 minute
    • Trigger a new sync

Partial Data Synced

Symptoms: Some records missing from your database

Solutions:

  1. Check sync completion

    • Verify sync status is "completed"
    • Review record count in sync history

  2. Verify table schema

    • Ensure all fields are nullable or have defaults
    • Check for schema mismatches

  3. Look for errors

    • Review sync logs for skipped records
    • Check your database logs for insert errors

  4. Re-run the sync

    • Trigger a fresh sync
    • CLS will update existing records

Table Schema Issues

Table Schema Mismatch

Symptoms: Error about incompatible columns or data types

Solutions:

  1. Use the provided SQL template

    • Copy the exact schema from CLS wizard
    • Don't modify column names or types

  2. Verify column types

    SELECT column_name, data_type
FROM information_schema.columns
WHERE table_name = 'your_table_name';

  3. Recreate the table

    DROP TABLE IF EXISTS your_table_name;
-- Then paste the SQL template from CLS

Dropping a table deletes all data. Export your data first if needed.

Missing Columns

Symptoms: Sync fails with "column does not exist" error

Solution:

Add missing columns to your table:

ALTER TABLE your_table_name
ADD COLUMN column_name data_type;

Or recreate the table using the latest SQL template from CLS.

Performance Issues

Slow Syncs

Symptoms: Syncs take longer than expected

Normal behavior:

  • First sync: 5-10 minutes for 10,000 records
  • Subsequent syncs: 1-2 minutes

If slower:

  1. Check database performance

    • Monitor database CPU and memory
    • Check for slow queries
    • Consider upgrading your database plan

  2. Reduce data volume

    • Use more frequent syncs (Premium plans)
    • Split into multiple configurations

  3. Check network

    • Verify internet connection
    • Test during off-peak hours

Rate Limit Errors

Symptoms: Error about too many requests

Solutions:

  1. Provider rate limits (e.g., Stripe)

    • Reduce sync frequency
    • Space out manual syncs
    • Contact your provider for higher limits

  2. CLS rate limits (IP-based: 60 req/min general, 20 req/min for syncs)

    • Wait 1 minute before retrying
    • Space out manual sync triggers
    • Avoid triggering multiple syncs simultaneously

Schedule Issues

Schedule Not Running

Symptoms: Scheduled sync doesn't trigger

Checklist:

  • ✅ You have a Premium plan
  • ✅ Schedule is set to "active"
  • ✅ Configuration is "active"
  • ✅ Project is "active"
  • ✅ Correct timezone settings

Solutions:

  1. Verify all active statuses

    • Check project status
    • Check configuration status
    • Check schedule status

  2. Check quota

    • Ensure you haven't hit daily sync limit
    • Review usage statistics

  3. Review sync history

    • Look for skipped or failed runs
    • Check error messages

Authentication Issues

Session Expired

Symptoms: Logged out unexpectedly

Solutions:

  1. Log in again - Sessions expire after 24 hours
  2. Check browser cookies - Ensure cookies are enabled
  3. Try incognito mode - Rule out browser extensions

Can't Sign In

Symptoms: Login fails or hangs

Solutions:

  1. Verify email - Check spam folder for verification
  2. Reset password - Use "Forgot password" link
  3. Try OAuth - Use Google or GitHub sign-in
  4. Clear browser cache - Hard refresh (Ctrl+Shift+R)

Data Issues

Duplicate Records

Symptoms: Same record appears multiple times in your database

Cause: Table missing primary key on id column

Fix:

-- Add primary key constraint
ALTER TABLE your_table_name
ADD PRIMARY KEY (id);

-- Delete duplicates (keeps newest)
DELETE FROM your_table_name a
USING your_table_name b
WHERE a.id = b.id
AND a.synced_at < b.synced_at;

Data Not Updating

Symptoms: Changes in your provider account don't appear in your database

Solutions:

  1. Run a fresh sync - Manual or scheduled
  2. Check last_sync timestamp - Ensure sync is recent
  3. Verify upsert logic - Check if id matches

Getting Help

If you still need assistance:

  1. Check sync logs

    • Go to configuration details
    • Click "Sync History"
    • Copy error messages

  2. Check database logs

    • Go to your database provider's dashboard
    • Check database logs
    • Look for error details

Additional Resources

Previous
Stripe Setup
Next
Overview