Troubleshooting

Welcome to the Tinybird troubleshooting guide. This section helps you resolve common issues you might encounter when working with Tinybird and ClickHouse.

Common issues

ClickHouse errors

The most common issues you'll encounter are ClickHouse database errors. These typically occur when:

  • Using incorrect SQL syntax
  • Working with incompatible data types
  • Using functions with wrong arguments
  • Having issues with table structures or joins

Performance issues

Performance problems can arise from:

  • Large queries without proper limits
  • Missing indexes on frequently queried columns
  • Inefficient query patterns
  • Resource constraints

Configuration issues

Configuration problems might include:

  • Incorrect connection settings
  • Missing or invalid authentication tokens
  • Wrong data source configurations
  • Environment-specific issues

Getting help

Error documentation

We've documented the most common ClickHouse errors with detailed explanations and solutions:

Debugging tools

Use these tools to help diagnose issues:

  • Query Builder - Test queries before running them in production
  • CLI tools - Use tb commands to inspect and debug your setup
  • Logs - Check application and database logs for error details

Best practices

Follow these practices to avoid common issues:

  • Always test queries with small datasets first
  • Use appropriate data types for your columns
  • Implement proper error handling in your applications
  • Monitor query performance and resource usage
  • Keep your Tinybird CLI and tools updated

Quick reference

Common error categories

Error TypeDescriptionCommon Causes
Syntax ErrorsMalformed SQL queriesMissing keywords, incorrect punctuation
Type ErrorsData type mismatchesWrong column types, incompatible operations
Function ErrorsInvalid function usageWrong arguments, unsupported operations
Join ErrorsJOIN operation issuesIncompatible keys, missing conditions
Aggregation ErrorsAggregate function problemsNon-aggregate columns in GROUP BY

Error resolution workflow

  1. Identify the error - Read the error message carefully
  2. Check documentation - Look up the specific error code
  3. Understand the cause - Review the error explanation
  4. Apply the fix - Follow the provided solution
  5. Test the solution - Verify the fix works as expected

Need more help?

If you can't find a solution in this documentation:

See also