Troubleshooting

This guide covers common issues you may encounter when using Basecut, along with their solutions and debugging techniques.

Database Connection Issues

Connection Refused

Symptoms:

✗ Error: failed to connect to database
  dial tcp: connection refused

Solutions:

Verify database is running:
pg_isready -h localhost -p 5432

Check connection string format:

# Correct format
postgresql://user:password@host:5432/database

# Common mistakes
postgresql://host:5432  # Missing database name
postgresql://user@host  # Missing port

Test connectivity:

psql "$BASECUT_DATABASE_URL" -c "SELECT 1"

Check firewall rules:
- Ensure port 5432 is open
- For self-hosted agents, verify network security groups allow outbound connections

Host Not Found

Symptoms:

✗ Error: failed to connect to database
  dial tcp: lookup prod-db.internal: no such host

Solutions:

Verify hostname resolves:

nslookup prod-db.internal
dig prod-db.internal

Use IP address instead:

postgresql://user:pass@10.0.1.100:5432/myapp

For private databases without public access:
- Use local execution (default) instead of agent execution
- Or deploy self-hosted agents in the same VPC

Permission Denied

Symptoms:

✗ Error: permission denied for schema public
✗ Error: must be owner of table users

Solutions:

Grant SELECT permissions:

GRANT USAGE ON SCHEMA public TO basecut_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO basecut_user;

-- For future tables
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO basecut_user;

Verify user permissions:

-- Check what schemas user can access
SELECT schema_name
FROM information_schema.schemata
WHERE schema_name NOT LIKE 'pg_%' AND schema_name != 'information_schema';

-- Check table permissions
SELECT table_schema, table_name, privilege_type
FROM information_schema.table_privileges
WHERE grantee = 'basecut_user';

SSL/TLS Connection Errors

Symptoms:

✗ Error: SSL is not enabled on the server
✗ Error: certificate verify failed

Solutions:

For databases requiring SSL:

postgresql://user:pass@host:5432/db?sslmode=require

For self-signed certificates:

postgresql://user:pass@host:5432/db?sslmode=require&sslrootcert=/path/to/ca.crt

Disable SSL verification (dev only, not recommended for production):
postgresql://user:pass@host:5432/db?sslmode=disable

Authentication Failures

Invalid API Key

Symptoms:

✗ Error: Unauthorized: invalid API key
✗ Error: API key is invalid or expired

Solutions:

Verify API key is set:
echo $BASECUT_API_KEY
Re-authenticate:
basecut login
Check API key format:
- Live keys: bc_live_*
- Test keys: bc_test_*
- Ensure no extra spaces or newlines

For CI/CD, verify secret is correctly set:

# GitHub Actions
echo "${{ secrets.BASECUT_API_KEY }}" | wc -c  # Should be > 50

# GitLab CI
echo "$BASECUT_API_KEY" | wc -c

Check API key in dashboard:
- Login to basecut.dev
- Navigate to Settings → API Keys
- Verify key hasn’t been revoked

whoami Command Fails

Symptoms:

$ basecut whoami
not authenticated

Solutions:

Login again:
basecut login

Check credentials file:

cat ~/.basecut/credentials
# Should contain API key

Use the profile you logged into:
basecut whoami --profile staging

Snapshot Creation Issues

Extraction Limits Reached

Symptoms:

⚠ Warning: per_table limit (1000) reached for table 'users'
⚠ Warning: total row limit (50000) reached
✓ Snapshot created with partial data

Solutions:

Increase limits in basecut.yml:

limits:
  rows:
    per_table: 5000 # Increase per-table limit
    total: 200000 # Increase total budget

Add more specific WHERE clauses:

from:
  - table: users
    where: 'created_at > :since AND status = :status'
    params:
      since: '2024-01-01'
      status: 'active' # More specific filter

Use table-specific limits:

limits:
  rows:
    per_table: 1000
    tables:
      public.audit_logs: 100 # Limit noisy tables
      public.sessions: 0 # Unlimited for this table (use `exclude` to skip)

Foreign Key Constraint Violations

Symptoms:

✗ Error: foreign key constraint violation
  Table 'orders' references missing row in 'users'

Solutions:

This shouldn’t happen! Basecut automatically ensures referential integrity. If you see this:
- File a bug report at github.com/basecuthq/basecut/issues
- Include your basecut.yml configuration
- Include the error message and stack trace

Workaround - increase upstream depth:

traverse:
  parents: 15 # Follow parent relationships further
  children: 10

Timeout on Large Extractions

Symptoms:

✗ Error: context deadline exceeded
✗ Error: operation timed out after 300s

Solutions:

Use self-hosted agents instead of local execution:

# Instead of local execution (default)
basecut snapshot create --config basecut.yml

# Use agent execution for large datasets
basecut snapshot create --config basecut.yml --async

Reduce snapshot scope:

limits:
  rows:
    per_table: 1000 # Start smaller

Use sampling:

sampling:
  mode: 'first' # Faster than 'random'

Snapshot Restore Issues

Schema Validation Failures

Symptoms:

✗ Error: schema mismatch: table 'users' missing column 'email_verified'
✗ Error: snapshot schema version incompatible with target database

Solutions:

Run migrations first:

# Run migrations to match snapshot schema
npm run migrate

# Then restore
basecut snapshot restore dev-seed:latest --target "$BASECUT_DATABASE_URL"

Force restore (skip validation):
basecut snapshot restore dev-seed:latest --target "$BASECUT_DATABASE_URL" --force
Only use --force if you understand the schema differences. Missing columns or type changes can still fail during insert.
Inspect the exact snapshot reference you’re restoring:
basecut snapshot inspect dev-seed:latest --json

Duplicate Key Violations

Symptoms:

✗ Error: duplicate key value violates unique constraint "users_pkey"
  Key (id)=(123) already exists

Solutions:

Use —reset flag to truncate tables first:
basecut snapshot restore dev-seed:latest \ --target "$BASECUT_DATABASE_URL" \ --reset
--reset is destructive. It truncates all tables included in the snapshot before restoring.

Manually truncate conflicting tables:

TRUNCATE TABLE users, orders, line_items CASCADE;

Restore to empty database:

# Create fresh database
createdb myapp_test

# Restore snapshot
basecut snapshot restore dev-seed:latest \
  --target "postgresql://localhost:5432/myapp_test"

Foreign Key Cycle / Non-Deferrable Constraint Block

Symptoms:

✗ Error: Restore blocked: your database has foreign key constraints that cannot be satisfied during bulk insert.

This usually means your restore scope includes self-referential tables or FK cycles, and at least some of those constraints are NOT DEFERRABLE. Solutions:

Run FK preflight analysis first (recommended):
basecut snapshot restore dev-seed:latest \ --target "$BASECUT_DATABASE_URL" \ --analyze-fks
Use the output to identify blocking tables/constraints and whether nullable fallback is available.
If nullable fallback is available, run restore normally: Basecut will automatically use a two-phase strategy (INSERT with temporary NULLs, then backfill) for eligible nullable FK cycles.

Make blocking FK constraints deferrable (recommended long-term):

ALTER TABLE <schema>.<table>
ALTER CONSTRAINT <constraint_name>
DEFERRABLE INITIALLY DEFERRED;

Use unsafe bypass only as a last resort:
basecut snapshot restore dev-seed:latest \ --target "$BASECUT_DATABASE_URL" \ --unsafe-disable-fk-checks
--unsafe-disable-fk-checks disables FK enforcement during restore. Use only in controlled environments and validate integrity after restore.

Restore Too Slow

Symptoms:

Restore takes several minutes for small snapshots
Progress bar stuck at 0%

Solutions:

Check database connectivity:
ping -c 3 your-db-host

Use local database for faster restore:

# Instead of remote database
basecut snapshot restore dev-seed:latest --target "postgresql://remote:5432/db"

# Use local database
basecut snapshot restore dev-seed:latest --target "postgresql://localhost:5432/db"

Disable triggers during restore (advanced):

ALTER TABLE users DISABLE TRIGGER ALL;
-- Restore snapshot
ALTER TABLE users ENABLE TRIGGER ALL;

Storage Issues

S3 Access Denied

Symptoms:

✗ Error: failed to upload snapshot
  AccessDenied: User does not have PutObject permission

Solutions:

Verify AWS credentials:
aws s3 ls s3://your-bucket/
Check IAM policy grants s3:PutObject, s3:GetObject, and s3:ListBucket on your bucket. See Storage Providers for the full policy.

Use correct credentials:

export AWS_ACCESS_KEY_ID=your_key_id
export AWS_SECRET_ACCESS_KEY=your_secret_key

# Or use AWS CLI profile
aws configure

S3 Region/Endpoint Errors (Common with `--async`)

Symptoms:

✗ Error: failed to upload snapshot
  ... Invalid region ...

Why this happens:

Local runs can succeed using your local AWS profile region
--async runs execute on a self-hosted agent, which may not have the same region config

Solutions:

Set region in basecut.yml for S3 output:

output:
  provider: s3
  bucket: your-bucket
  region: us-east-1

For Cloudflare R2 / S3-compatible endpoints, set both endpoint and region:

output:
  provider: s3
  bucket: your-r2-bucket
  region: auto
  endpoint: https://<accountid>.r2.cloudflarestorage.com

If you cannot set output.region, ensure AWS_REGION is set on the agent environment.

GCS Permission Errors

Symptoms:

✗ Error: failed to upload to GCS
  403: Forbidden

Solutions:

Verify GCS credentials:
gsutil ls gs://your-bucket/

Check service account permissions:

gcloud storage buckets add-iam-policy-binding gs://your-bucket \
  --member=serviceAccount:basecut@project.iam.gserviceaccount.com \
  --role=roles/storage.objectAdmin

Use correct credentials:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

# Or use gcloud auth
gcloud auth application-default login

Snapshot Not Found

Symptoms:

✗ Error: snapshot not found: dev-seed:latest
✗ Error: no versions found for snapshot 'dev-seed'

Solutions:

List available snapshots:
basecut snapshot list --name dev-seed

Check snapshot name spelling:

# Common mistake: wrong name
basecut snapshot restore dev-seed:latest  # Wrong
basecut snapshot restore dev-data:latest  # Correct

Verify storage provider configuration:

# In basecut.yml
output:
  provider: s3
  bucket: your-bucket # Ensure this matches where snapshot was created
  region: us-east-1

Self-Hosted Agent Issues

Agent Not Picking Up Jobs

Symptoms:

Jobs submitted with --async never complete
Agent logs show no activity

Solutions:

Check agent logs:
docker logs basecut-agent

Verify API key format and org access:

echo "$BASECUT_API_KEY" | grep -E '^bc_(live|test)_'

Check network connectivity to Basecut API:

docker exec basecut-agent curl https://api.basecut.dev/health

Verify agent registration:
- Check dashboard for registered agents
- Ensure agent is in “Active” state

Agent Database Connection Failures

Symptoms:

Agent log: failed to connect to database
Agent log: dial tcp: i/o timeout

Solutions:

Test database access from agent:

docker exec basecut-agent psql "$BASECUT_DATABASE_URL" -c "SELECT 1"

Check network security groups:
- Verify agent’s security group allows outbound to database port
- Verify database’s security group allows inbound from agent

Use private IP for database in same VPC:

# Instead of public IP
postgresql://user:pass@1.2.3.4:5432/db

# Use private IP
postgresql://user:pass@10.0.1.100:5432/db

Performance Issues

Slow Extractions

Symptoms:

Snapshot creation takes hours
“Extracting…” stuck at same table count

Solutions:

Check database indexes:

-- Ensure foreign key columns are indexed
CREATE INDEX CONCURRENTLY idx_orders_user_id ON orders(user_id);
CREATE INDEX CONCURRENTLY idx_line_items_order_id ON line_items(order_id);

Use sampling instead of full extraction:

sampling:
  mode: 'first' # Much faster than 'random'

Reduce traversal depth:

traverse:
  parents: 3 # Reduce from 10
  children: 5 # Reduce from 10

Use agent execution for large datasets:

basecut snapshot create --config basecut.yml --async

Debugging Techniques

Check Configuration Parsing

Verify YAML syntax:

# Use a YAML validator
python -c "import yaml; yaml.safe_load(open('basecut.yml'))"

Test Individual Components

Test database connection:

psql "$BASECUT_DATABASE_URL" -c "SELECT current_database(), current_user;"

Test storage access:

# S3
aws s3 cp test.txt s3://your-bucket/test.txt

# GCS
echo "test" | gsutil cp - gs://your-bucket/test.txt

# Local
touch /path/to/snapshots/test.txt

Getting Help

If you’ve tried the solutions above and still have issues:

Check the logs:
- Agent: docker logs basecut-agent
File a GitHub issue:
- github.com/basecuthq/basecut/issues
- Include: error message, configuration file, command used, Basecut version
Contact support:
- Email: support@basecut.dev
- Include: account email, snapshot name, timestamp of error

Next Steps

Environment Variables

Complete configuration reference

Agent Deployment

Self-hosted agent setup and debugging

CLI Reference

Complete command documentation

​Database Connection Issues

​Connection Refused

​Host Not Found

​Permission Denied

​SSL/TLS Connection Errors

​Authentication Failures

​Invalid API Key

​whoami Command Fails

​Snapshot Creation Issues

​Extraction Limits Reached

​Foreign Key Constraint Violations

​Timeout on Large Extractions

​Snapshot Restore Issues

​Schema Validation Failures

​Duplicate Key Violations

​Foreign Key Cycle / Non-Deferrable Constraint Block

​Restore Too Slow

​Storage Issues

​S3 Access Denied

​S3 Region/Endpoint Errors (Common with --async)

​GCS Permission Errors

​Snapshot Not Found

​Self-Hosted Agent Issues

​Agent Not Picking Up Jobs

​Agent Database Connection Failures

​Performance Issues

​Slow Extractions

​Debugging Techniques

​Check Configuration Parsing

​Test Individual Components

​Getting Help

​Next Steps

Environment Variables

Agent Deployment

CLI Reference

Database Connection Issues

Connection Refused

Host Not Found

Permission Denied

SSL/TLS Connection Errors

Authentication Failures

Invalid API Key

whoami Command Fails

Snapshot Creation Issues

Extraction Limits Reached

Foreign Key Constraint Violations

Timeout on Large Extractions

Snapshot Restore Issues

Schema Validation Failures

Duplicate Key Violations

Foreign Key Cycle / Non-Deferrable Constraint Block

Restore Too Slow

Storage Issues

S3 Access Denied

S3 Region/Endpoint Errors (Common with `--async`)

GCS Permission Errors

Snapshot Not Found

Self-Hosted Agent Issues

Agent Not Picking Up Jobs

Agent Database Connection Failures

Performance Issues

Slow Extractions

Debugging Techniques

Check Configuration Parsing

Test Individual Components

Getting Help

Next Steps