Common Errors

This guide covers frequently encountered errors in FactoryThread and how to resolve them. If you don't find your issue here, check the Dashboard page for execution-specific error details.

Connection Errors

"Connection refused"

What it means: The server actively refused the connection attempt.

Possible causes:

• Database server is not running
• Firewall blocking the connection
• Wrong port number
• Server not accepting remote connections

Solutions:

1. Verify the server is running and accessible
2. Check firewall rules allow connections on the specified port
3. Confirm the port number in your connection settings
4. Ensure the database is configured to accept remote connections
5. Try connecting from the same network as the server

"Connection timeout"

What it means: The connection attempt took too long and was cancelled.

Possible causes:

• Network connectivity issues
• Server is overloaded
• Firewall silently dropping packets
• Very high network latency

Solutions:

1. Check your network connection
2. Verify the server hostname/IP is correct
3. Try pinging the server to test connectivity
4. Increase connection timeout in advanced settings
5. Check for network path issues (traceroute)

"Authentication failed"

What it means: The username or password was rejected.

Possible causes:

• Incorrect username or password
• User account locked or disabled
• Password expired
• Wrong authentication method
• User doesn't have connect permission

Solutions:

1. Verify username and password are correct
2. Check that the user account exists and is active
3. Confirm the authentication method matches the server
4. Test credentials with a database client tool
5. Contact your database administrator if needed

"Database does not exist"

What it means: The specified database name wasn't found on the server.

Possible causes:

• Typo in database name
• Database was renamed or deleted
• User doesn't have access to the database
• Case sensitivity issues

Solutions:

1. Verify the exact database name (check case sensitivity)
2. Confirm the database exists on the server
3. Ensure the connection user has access to the database
4. List available databases to find the correct name

"SSL certificate error"

What it means: The secure connection couldn't be established due to certificate issues.

Possible causes:

• Self-signed certificate not trusted
• Certificate expired
• Hostname mismatch
• Missing CA certificate

Solutions:

1. For development: enable "Trust Server Certificate"
2. For production: install the proper CA certificate
3. Verify the hostname matches the certificate
4. Check certificate expiration date
5. Contact your IT team for proper certificate configuration

Execution Errors

"Data type mismatch"

What it means: A value couldn't be converted to the expected type.

Possible causes:

• Trying to convert non-numeric text to number
• Date format doesn't match expected pattern
• Null value where not allowed
• Incompatible types in merge/join

Solutions:

1. Add a Convert node before the failing transformation
2. Use CAST or type conversion functions
3. Handle nulls with COALESCE
4. Check source data for unexpected values
5. Add filters to exclude invalid data

"Null reference error"

What it means: The workflow tried to access data that doesn't exist.

Possible causes:

• Accessing properties of null objects
• Missing fields in source data
• Join/lookup returned no matches
• Empty result set processed incorrectly

Solutions:

1. Add null checks in transformations: COALESCE(${Field}, 'default')
2. Use Left join instead of Inner join if matches aren't guaranteed
3. Filter out null values before processing
4. Verify source data contains expected fields
5. Handle empty results gracefully

"Execution timeout"

What it means: The workflow took too long and was cancelled.

Possible causes:

• Processing very large datasets
• Slow database queries
• External API delays
• Infinite loops (rare, but possible)

Solutions:

1. Add row limits during development/testing
2. Optimize database queries (add indexes, improve SQL)
3. Filter data earlier in the workflow
4. Process data in smaller batches
5. Increase timeout settings if necessary

"Invalid expression"

What it means: The expression syntax is incorrect.

Possible causes:

• Typo in function name
• Missing or extra parentheses
• Wrong number of arguments
• Invalid field reference

Solutions:

1. Check function spelling and case
2. Count parentheses - each opening needs a closing
3. Review function documentation for correct arguments
4. Verify field names match exactly (including case)
5. Test expressions with simple values first

"Schema mismatch"

What it means: The data structure doesn't match what was expected.

Possible causes:

• Source schema changed since workflow was created
• Renamed or removed columns
• Different data types than expected
• Different connections with similar entities

Solutions:

1. Refresh the entity in the connection
2. Update field mappings in affected nodes
3. Check for schema changes in the source system
4. Re-select the entity to get updated schema
5. Preview data to verify structure

Merge and Join Errors

"No matching rows found"

What it means: A join or lookup found no matches between the datasets.

Possible causes:

• Join keys don't have matching values
• Data type mismatch in join keys (text vs number)
• Leading/trailing spaces in text keys
• Case sensitivity differences

Solutions:

1. Preview both datasets to verify matching values exist
2. Ensure join key types match
3. Use TRIM() on text keys to remove spaces
4. Use UPPER() or LOWER() for case-insensitive matching
5. Consider using Left join if matches aren't guaranteed

"Duplicate key violation"

What it means: When writing data, a unique constraint was violated.

Possible causes:

• Trying to insert a duplicate primary key
• Unique index constraint violated
• Race condition with concurrent operations

Solutions:

1. Use Upsert mode instead of Insert
2. Add Distinct node before writing
3. Check for duplicates in source data
4. Verify the correct key fields are used
5. Handle conflicts in your workflow logic

API and HTTP Errors

"401 Unauthorized"

What it means: Authentication is required but wasn't provided or was invalid.

Solutions:

1. Verify your API key is correct and active
2. Check the Authorization header format
3. Ensure the API key has permission for this operation
4. Regenerate the API key if needed

"403 Forbidden"

What it means: Authentication succeeded but you don't have permission.

Solutions:

1. Check that your API key has the necessary scope
2. Verify your user has permission for the operation
3. Contact your workspace admin for access

"404 Not Found"

What it means: The requested resource doesn't exist.

Solutions:

1. Verify the URL is correct
2. Check that the flow is deployed
3. Ensure path parameters are correct
4. Confirm the resource hasn't been deleted

"429 Too Many Requests"

What it means: You've exceeded the rate limit.

Solutions:

1. Reduce request frequency
2. Add delays between requests
3. Batch operations when possible
4. Contact support for rate limit increases

"500 Internal Server Error"

What it means: Something went wrong on the server.

Solutions:

1. Check execution details in Insights
2. Review input data for issues
3. Try the operation again
4. Check for system status issues
5. Contact support with the execution ID

Performance Issues

Slow Executions

Symptoms: Workflows take longer than expected.

Solutions:

1. Filter early to reduce data volume
2. Select only needed columns
3. Add database indexes on frequently queried columns
4. Avoid N+1 query patterns
5. Use batch operations for writes

Memory Issues

Symptoms: Large datasets cause failures or slowdowns.

Solutions:

1. Process data in smaller batches
2. Limit rows during testing
3. Stream data instead of loading all at once
4. Remove unnecessary columns early

Getting More Help

In Execution Details

The Insights page shows:

• Full error messages
• Stack traces (technical details)
• Which step failed
• Input and output data

Reproducing Issues

To debug effectively:

1. Note the exact error message
2. Copy the input data
3. Open the workflow in Designer
4. Use Preview with the same input
5. Step through node by node

Contacting Support

When reporting issues, include:

• Execution ID (from Insights)
• Error message
• Steps to reproduce
• Expected vs actual behavior

Next Steps

• Dashboard - Monitor executions
• Connections Overview - Connection management
• Designer Overview - Workflow building