Common Issues

This guide provides solutions to frequently encountered issues in Datalinx AI.

Connection Issues

Cannot Connect to Database

Symptoms: Connection test fails with timeout or refused error.

Possible Causes & Solutions:

Cause	Solution
Firewall blocking	Whitelist Datalinx AI IP addresses
Wrong host/port	Verify connection details in your database admin panel
SSL required	Enable SSL in advanced connection settings
VPC isolation	Configure SSH tunnel for private databases

Diagnostic Steps:

1. Verify the database is accessible from your network
2. Test connection with a database client (psql, mysql)
3. Check firewall rules and security groups
4. Review database server logs for connection attempts

Authentication Failed

Symptoms: Connection test fails with authentication error.

Solutions:

-- PostgreSQL: Verify user has login privilege
SELECT usename, usesuper, usecreatedb
FROM pg_user WHERE usename = 'datalinx_user';

-- Grant necessary permissions
GRANT CONNECT ON DATABASE mydb TO datalinx_user;
GRANT USAGE ON SCHEMA public TO datalinx_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO datalinx_user;

SSL Handshake Failed

Symptoms: SSL/TLS connection errors.

Solutions:

1. Verify SSL is enabled on your database server
2. Check certificate validity - ensure it's not expired
3. Try different SSL modes: require, verify-ca, verify-full
4. Update CA certificates if using custom certificates

Mapping Issues

Mapping Validation Errors

Error: "Required field not mapped"

Solution: Ensure all required target fields have a mapping:

1. Open the mapping in the editor
2. Look for fields marked with asterisk (*)
3. Map each required field to a source or expression

Error: "Type mismatch"

Solution: Ensure data types are compatible:

-- Convert string to integer
CAST(user_id_str AS INTEGER)

-- Convert timestamp to date
DATE(created_at)

-- Convert number to string
CAST(amount AS VARCHAR)

Transformation Expression Errors

Error: "Invalid SQL expression"

Common Causes:

Issue	Example	Fix
Missing quotes	John	'John'
Wrong function	LENGTH(name)	CHAR_LENGTH(name)
NULL handling	a + b	COALESCE(a, 0) + COALESCE(b, 0)
Type mismatch	CONCAT(name, age)	CONCAT(name, CAST(age AS VARCHAR))

Pipeline Issues

Pipeline Fails Immediately

Symptoms: Pipeline fails within seconds of starting.

Checklist:

1. Source connection is valid and tested
2. Target connection is valid and tested
3. All mappings are in "Valid" status
4. User has permission to run pipelines
5. Required credentials are not expired

Pipeline Runs Slowly

Symptoms: Pipeline takes much longer than expected.

Optimization Steps:

1. Enable incremental loading:

   Incremental Config:
     Cursor Column: updated_at
     Batch Size: 10000

2. Add source indexes:

   CREATE INDEX idx_orders_updated ON orders(updated_at);

3. Reduce data volume:

   • Add filters to source query
   • Limit date ranges
   • Exclude unnecessary columns

Pipeline Data Mismatch

Symptoms: Row counts don't match between source and target.

Diagnostic Steps:

1. Check for filters in mapping or pipeline configuration
2. Look for NULL handling that might exclude rows
3. Verify deduplication settings
4. Review transformation errors in pipeline logs

Authentication Issues

Cannot Log In

Symptoms: Login fails with incorrect credentials.

Solutions:

1. Reset password via "Forgot Password" link
2. Check caps lock - passwords are case-sensitive
3. Clear browser cache and cookies
4. Try incognito/private browsing
5. Contact admin if account may be deactivated

SSO Not Working

Symptoms: SSO redirect fails or loops.

Diagnostic Steps:

1. Verify SSO is enabled for your organization
2. Check Identity Provider status
3. Confirm email domain matches SSO configuration
4. Review IdP logs for authentication errors

MFA Issues

Symptoms: MFA code rejected or device lost.

Solutions:

Issue	Solution
Code rejected	Check device time sync, try next code
Device lost	Use backup codes
No backup codes	Contact organization admin to reset MFA

API Issues

API Rate Limited

Error: 429 Too Many Requests

Solutions:

1. Implement exponential backoff
2. Reduce request frequency
3. Batch operations where possible
4. Upgrade plan for higher limits

API Key Invalid

Error: 401 Unauthorized

Checklist:

1. Key is correctly copied (no extra spaces)
2. Key has not expired
3. Key has not been revoked
4. Using correct header format: Authorization: Bearer <key>
5. Key has permissions for the endpoint

Getting Help

If you can't resolve your issue:

1. Search documentation - use the search bar
2. Check status page - for known outages
3. Review release notes - recent changes may affect behavior
4. Contact support: support@datalinx.ai

Related Documentation

• Error Reference - Complete error code guide
• FAQ - Frequently asked questions
• Security Architecture - Security troubleshooting