From 32feb0b86938adb5ad6a9c343713caf500289d53 Mon Sep 17 00:00:00 2001 From: Dominic Tran Date: Sat, 26 Jul 2025 09:59:37 -0500 Subject: [PATCH] Troubleshooting page, temporary placement --- .../troubleshooting/troubleshooting.md | 145 ++++++++++++++++++ knowledgebase/find-expensive-queries.mdx | 1 + ...ding_expensive_queries_by_memory_usage.mdx | 1 + sidebars.js | 14 ++ 4 files changed, 161 insertions(+) create mode 100644 docs/getting-started/troubleshooting/troubleshooting.md diff --git a/docs/getting-started/troubleshooting/troubleshooting.md b/docs/getting-started/troubleshooting/troubleshooting.md new file mode 100644 index 00000000000..d6e6f9b7103 --- /dev/null +++ b/docs/getting-started/troubleshooting/troubleshooting.md @@ -0,0 +1,145 @@ +--- +sidebar_position: 1 +slug: /getting-started/troubleshooting +sidebar_label: 'Troubleshooting' +keywords: [ + 'clickhouse troubleshooting', + 'clickhouse errors', + 'slow queries', + 'memory problems', + 'connection issues', + 'performance optimization', + 'database errors', + 'configuration problems', + 'debug', + 'solutions' +] +title: 'Troubleshooting Common Issues' +description: 'Find solutions to the most common ClickHouse problems including slow queries, memory errors, connection issues, and configuration problems.' +--- + +# Troubleshooting Common Issues {#troubleshooting-common-issues} + +Having problems with ClickHouse? Find the solutions to common issues here. + +## Performance and Errors {#performance-and-errors} + +Queries running slowly, timeouts, or getting specific error messages like "Memory limit exceeded" or "Connection refused." + +
+Show performance and error solutions + +### Query Performance {#query-performance} +- [Find which queries are using the most resources](/knowledgebase/find-expensive-queries) +- [Complete query optimization guide](/docs/optimize/query-optimization) +- [Optimize JOIN operations](/docs/best-practices/minimize-optimize-joins) +- [Run diagnostic queries to find bottlenecks](/docs/knowledgebase/useful-queries-for-troubleshooting) +
+### Data Insertion Performance {#data-insertion-performance} +- [Speed up data insertion](/docs/optimize/bulk-inserts) +- [Set up asynchronous inserts](/docs/optimize/asynchronous-inserts) +
+### Advanced Analysis Tools {#advanced-analysis-tools} +- [Profile with LLVM XRay](/docs/knowledgebase/profiling-clickhouse-with-llvm-xray) +- [Check what processes are running](/docs/knowledgebase/which-processes-are-currently-running) +- [Monitor system performance](/docs/operations/system-tables/processes) +
+### Error Messages {#error-messages} +- **"Memory limit exceeded"** → [Debug memory limit errors](/docs/guides/developer/debugging-memory-issues) +- **"Connection refused"** → [Fix connection problems](#connections-and-authentication) +- **"Login failures"** → [Set up users, roles, and permissions](/docs/operations/access-rights) +- **"SSL certificate errors"** → [Fix certificate problems](/docs/knowledgebase/certificate_verify_failed_error) +- **"Table/database errors"** → [Database creation guide](/docs/sql-reference/statements/create/database) | [Table UUID problems](/docs/engines/database-engines/atomic) +- **"Network timeouts"** → [Network troubleshooting](/docs/interfaces/http) +- **Other issues** → [Track errors across your cluster](/docs/operations/system-tables/errors) +
+ +## Memory and Resources {#memory-and-resources} + +High memory usage, out-of-memory crashes, or need help sizing your ClickHouse deployment. + +
+Show memory solutions + +### Memory debugging and monitoring: {#memory-debugging-and-monitoring} +- [Identify what's using memory](/docs/guides/developer/debugging-memory-issues) +- [Check current memory usage](/docs/operations/system-tables/processes) +- [Memory allocation profiling](/docs/operations/allocation-profiling) +- [Analyze memory usage patterns](/docs/operations/system-tables/query_log) +
+### Memory configuration: {#memory-configuration} +- [Configure memory limits](/docs/operations/settings/memory-overcommit) +- [Server memory settings](/docs/operations/server-configuration-parameters/settings) +- [Session memory settings](/docs/operations/settings/settings) +
+### Scaling and sizing: {#scaling-and-sizing} +- [Right-size your service](/docs/operations/tips) +- [Configure automatic scaling](/docs/manage/scaling) + +
+ +## Connections and Authentication {#connections-and-authentication} + +Can't connect to ClickHouse, authentication failures, SSL certificate errors, or client setup issues. + +
+Show connection solutions + +### Basic Connection Issues {#basic-connection-issues} +- [Fix HTTP interface issues](/docs/interfaces/http) +- [Handle SSL certificate problems](/docs/knowledgebase/certificate_verify_failed_error) +- [User authentication setup](/docs/operations/access-rights) +
+### Client Interfaces {#client-interfaces} +- [Native ClickHouse clients](/docs/interfaces/natives-clients-and-interfaces) +- [MySQL interface problems](/docs/interfaces/mysql) +- [PostgreSQL interface issues](/docs/interfaces/postgresql) +- [gRPC interface configuration](/docs/interfaces/grpc) +- [SSH interface setup](/docs/interfaces/ssh) +
+### Network and Data {#network-and-data} +- [Network security settings](/docs/operations/server-configuration-parameters/settings) +- [Data format parsing issues](/docs/interfaces/formats) + +
+ +## Setup and Configuration {#setup-and-configuration} + +Initial installation, server configuration, database creation, data ingestion issues, or replication setup. + +
+Show setup and configuration solutions + +### Initial Setup {#initial-setup} +- [Configure server settings](/docs/operations/server-configuration-parameters/settings) +- [Set up security and access control](/docs/operations/access-rights) +- [Configure hardware properly](/docs/operations/tips) +
+### Database Management {#database-management} +- [Create and manage databases](/docs/sql-reference/statements/create/database) +- [Choose the right table engine](/docs/engines/table-engines) + +
+### Data Operations {#data-operations} +- [Optimize bulk data insertion](/docs/optimize/bulk-inserts) +- [Handle data format problems](/docs/interfaces/formats) +- [Set up streaming data pipelines](/docs/optimize/asynchronous-inserts) +- [Improve S3 integration performance](/docs/integrations/s3/performance) +
+### Advanced Configuration {#advanced-configuration} +- [Set up data replication](/docs/engines/table-engines/mergetree-family/replication) +- [Configure distributed tables](/docs/engines/table-engines/special/distributed) + +- [Set up backup and recovery](/docs/operations/backup) +- [Configure monitoring](/docs/operations/system-tables/overview) + +
+ +## Still Need Help? {#still-need-help} + +If you can't find a solution: + +1. **Check system tables** - Run `SELECT * FROM system.processes` and `SELECT * FROM system.query_log ORDER BY event_time DESC LIMIT 10` +2. **Review server logs** - Look for error messages in your ClickHouse logs +3. **Ask the community** - [GitHub Discussions](https://github.com/ClickHouse/ClickHouse/discussions) +4. **Get professional support** - [ClickHouse Cloud support](https://clickhouse.com/support) \ No newline at end of file diff --git a/knowledgebase/find-expensive-queries.mdx b/knowledgebase/find-expensive-queries.mdx index db30bd4a81d..5e1e59e6bdf 100644 --- a/knowledgebase/find-expensive-queries.mdx +++ b/knowledgebase/find-expensive-queries.mdx @@ -2,6 +2,7 @@ title: How to Identify the Most Expensive Queries in ClickHouse description: Learn how to use the `query_log` table in ClickHouse to identify the most memory and CPU-intensive queries across distributed nodes. date: 2023-03-26 +slug: find-expensive-queries tags: ['Performance and Optimizations'] keywords: ['Expensive Queries'] --- diff --git a/knowledgebase/finding_expensive_queries_by_memory_usage.mdx b/knowledgebase/finding_expensive_queries_by_memory_usage.mdx index 100a8317d96..6f55d1c57b1 100644 --- a/knowledgebase/finding_expensive_queries_by_memory_usage.mdx +++ b/knowledgebase/finding_expensive_queries_by_memory_usage.mdx @@ -2,6 +2,7 @@ title: Identifying Expensive Queries by Memory Usage in ClickHouse description: Learn how to use the `system.query_log` table to find the most memory-intensive queries in ClickHouse, with examples for clustered and standalone setups. date: 2023-06-07 +slug: find-expensive-queries-by-memory-usage tags: ['Performance and Optimizations'] keywords: ['Expensive Queries', 'Memory Usage'] --- diff --git a/sidebars.js b/sidebars.js index 680dd81d17c..09372908775 100644 --- a/sidebars.js +++ b/sidebars.js @@ -254,6 +254,20 @@ const sidebars = { dirName: "getting-started/example-datasets", } ] + }, + { + type: "category", + label: "Troubleshooting", + className: "top-nav-item", + collapsed: true, + collapsible: true, + link: { type: "doc", id: "getting-started/index" }, + items: [ + { + type: "autogenerated", + dirName: "getting-started/troubleshooting", + } + ] } ],