Troubleshooting

Common issues and solutions when using Sling.

Connection Issues

Connection Refused

code

Error: failed to connect to database

Solutions:

•Check host/port accessibility: telnet host port
•Verify firewall rules allow traffic
•Confirm database is running
•Check for VPN requirements

Authentication Failed

code

Error: authentication failed for user

Solutions:

•Verify username and password
•Check user has required permissions
•Review database authentication logs
•Confirm SSL/TLS settings match

SSL/TLS Errors

code

Error: SSL certificate problem

Solutions:

•For testing: add sslmode=disable (not for production)
•Verify certificate validity
•Check SSL configuration matches server
•Ensure CA certificates are available

Test Connection

bash

# Via CLI
sling conns test MY_CONN --debug

# Via MCP
{"action": "test", "input": {"connection": "MY_CONN", "debug": true}}

Replication Issues

Table Not Found

code

Error: table "schema.table" does not exist

Solutions:

•Discover available tables:

bash

sling conns discover MY_CONN --pattern "schema.*"

•Check case sensitivity (some DBs are case-sensitive)
•Verify user has SELECT permission

Type Conversion Errors

code

Error: cannot convert value to target type

Solutions:

•Add explicit type casting:

yaml

columns:
  problematic_col: string
transforms:
  - problematic_col: 'cast(value, "integer")'

•Handle nulls:

yaml

transforms:
  - amount: 'coalesce(value, 0)'

•Clean data:

yaml

transforms:
  - value: 'replace(value, "[^0-9]", "")'

Primary Key Violations

code

Error: duplicate key value violates unique constraint

Solutions:

•Verify primary key is correct
•Check for duplicate source data
•Use mode: full-refresh to replace data
•Deduplicate in source query

Memory Issues

code

Error: out of memory processing large dataset

Solutions:

•
Reduce batch size:
yaml
```
env:
  SLING_BATCH_SIZE: 5000
```
•
Enable chunking:
yaml
```
source_options:
  chunk_size: 6h
```

•Use file splitting:

yaml

target_options:
  file_max_rows: 100000

•
Reduce parallelism:
yaml
```
env:
  SLING_THREADS: 2
```

Performance Issues

Slow Performance

Database sources:

•
Increase threads:
yaml
```
env:
  SLING_THREADS: 10
```
•
Enable bulk loading:
yaml
```
target_options:
  use_bulk: true
```
•Use incremental mode instead of full-refresh

File sources:

•
Use parallel file processing:
yaml
```
env:
  SLING_THREADS: 20
```
•
Compress output files:
yaml
```
target_options:
  compression: snappy
```

High Memory Usage

•Stream large tables with chunking
•Reduce batch sizes
•Process fewer concurrent streams

Debug Options

Enable Debug Logging

bash

# CLI
sling run -r replication.yaml --debug

# MCP
{"action": "run", "input": {"file_path": "...", "env": {"DEBUG": "true"}}}

Enable Trace Logging

bash

sling run -r replication.yaml --trace

Validate Configuration

bash

# Parse only (no execution)
sling run -r replication.yaml --parse

# Or via MCP
{"action": "parse", "input": {"file_path": "replication.yaml"}}

API Spec Issues

Rate Limiting

code

Error: 429 Too Many Requests

Solutions:

•Reduce request rate:

yaml

defaults:
  request:
    rate: 1  # Requests per second

•Configure retry:

yaml

response:
  rules:
    - action: retry
      condition: response.status == 429
      max_attempts: 5
      backoff: exponential

Authentication Errors

code

Error: 401 Unauthorized

Solutions:

•Verify API credentials
•Check token expiration
•Confirm required scopes
•Test with curl first

Pagination Loops

API keeps returning same data.

Solutions:

•Check pagination stop_condition
•Verify cursor/offset updates correctly

•Debug with limit:

yaml

response:
  records:
    limit: 100  # Stop after 100 records

File Issues

File Not Found

code

Error: file not found

Solutions:

•Check file path exists
•Verify connection configuration
•Confirm user has read access
•Check for typos in path

Encoding Errors

code

Error: invalid character encoding

Solutions:

•Specify encoding:

yaml

source_options:
  encoding: utf8  # or latin1, windows1252

•Clean source data

Format Detection Failed

Solutions:

•Explicitly set format:

yaml

source_options:
  format: csv
  header: true
  delimiter: ','

Error Recovery

Resume Failed Replications

Sling tracks progress automatically. Re-run to resume.

Retry Configuration

yaml

env:
  SLING_RETRIES: 3
  SLING_RETRY_DELAY: 60s

Run Specific Streams

bash

# CLI
sling run -r replication.yaml --select "failed_table"

# MCP
{"action": "run", "input": {"file_path": "...", "select_streams": ["failed_table"]}}

Getting Help

•Debug output: Run with --debug or --trace
•Parse first: Validate config before running
•Test connections: Always test before replicating
•Check logs: Review database/API logs

Support Channels

•Docs: https://docs.slingdata.io
•Discord: https://discord.gg/q5xtaSNDvp
•GitHub Issues: https://github.com/slingdata-io/sling-cli/issues
•Email: support@slingdata.io