Troubleshooting Guide

Common Issues

This guide covers the most common problems you might encounter and how to solve them.

Connection Issues

Connection Test Fails

Problem: You see “Connection test failed” when adding a connection.Symptoms:

$ queryly connect add
? Connection name: MyDB
? Database type: SQLite
? Connection string: Data Source=mydb.db

Testing connection...
✗ Connection test failed: Unable to open database file

Solutions:

Verify Connection String Format Ensure you’re using the correct format for your database type:
Data Source=./mydb.db
Check Database File Exists (SQLite)
```
# Verify the file exists
ls -la mydb.db

# Check the path is correct
pwd  # See current directory
```
Use absolute paths if relative paths aren’t working: Data Source=/full/path/to/mydb.db

Verify Read Permissions

# Check file permissions (macOS/Linux)
ls -l mydb.db

# Give yourself read access if needed
chmod 644 mydb.db

Test Database Connection Separately
sqlite3 mydb.db "SELECT 1;"

Check Network Connectivity (Remote Databases)

# Test if server is reachable
ping db.example.com

# Test if port is open
telnet db.example.com 5432  # PostgreSQL
telnet db.example.com 3306  # MySQL
telnet db.example.com 1433  # SQL Server

Connection String Not Accepted

Problem: Your connection string format is rejected.Solutions:

Remove Quotes: Don’t wrap the connection string in quotes

# ✗ Incorrect
"Data Source=mydb.db"

# ✓ Correct
Data Source=mydb.db

Check for Typos: Common mistakes include:
- DataSource instead of Data Source (SQLite)
- Username instead of User (MySQL)
- UserId instead of User Id (SQL Server)

Escape Special Characters: If your password contains special characters:

# Use URL encoding or escape characters
Password=my%40password  # @ symbol encoded

'Connection Not Found' Error

Problem: Queryly can’t find a connection you know you saved.Solutions:

List All Connections
```
queryly connect list
```
Verify the exact name (case-sensitive).

Check Configuration File

# macOS/Linux
cat ~/.queryly/connections.json

# Windows (PowerShell)
Get-Content $env:USERPROFILE\.queryly\connections.json

Verify JSON Syntax If you manually edited the file, ensure it’s valid JSON:

# Validate JSON (if jq is installed)
jq empty ~/.queryly/connections.json

Installation Issues

Command Not Found

Problem: You see queryly: command not found when trying to run Queryly.Symptoms:

$ queryly connect list
queryly: command not found

Solutions:

Use Full dotnet run Command Queryly is not installed as a global tool yet. Run it with:
```
dotnet run --project src/Queryly.CLI/Queryly.CLI.csproj
```

Create an Alias (macOS/Linux) Add to your ~/.bashrc or ~/.zshrc:

alias queryly='dotnet run --project /path/to/queryly/src/Queryly.CLI/Queryly.CLI.csproj'

Then reload:

source ~/.bashrc  # or ~/.zshrc

Check .NET SDK Installation
```
dotnet --version
```
Should output version 8.0 or higher. If not installed:
```
# Download from:
# https://dotnet.microsoft.com/download
```
Verify Project Build
```
cd /path/to/queryly
dotnet build
```

.NET SDK Not Found

Problem: Error about missing .NET SDK.Solutions:

Install .NET 8.0 SDK Download from: https://dotnet.microsoft.com/download
brew install --cask dotnet-sdk
Verify Installation
```
dotnet --list-sdks
```

Schema and Data Issues

No Tables Found

Problem: “No tables found” message when listing schema.Symptoms:

$ queryly schema list MyDB
No tables found in database.

Solutions:

Verify Database Has Tables Use another tool to confirm:

# SQLite
sqlite3 mydb.db ".tables"

# PostgreSQL
psql -h localhost -U postgres -d mydb -c "\dt"

# MySQL
mysql -h localhost -u root -p mydb -e "SHOW TABLES;"

Check Connection String Points to Correct Database
```
queryly connect test MyDB
```
Verify the database name in the output.

Verify Permissions Ensure your database user has permission to read schema:

-- PostgreSQL: Check permissions
SELECT * FROM information_schema.table_privileges 
WHERE grantee = 'your_username';

Check Schema Name (SQL Server/PostgreSQL) Some databases use schemas. Queryly defaults to common schemas, but you might need a different one:

-- PostgreSQL: List all schemas
SELECT schema_name FROM information_schema.schemata;

-- SQL Server: List schemas
SELECT name FROM sys.schemas;

Table Data Not Displaying

Problem: queryly data browse shows no rows when you know the table has data.Solutions:

Verify Table Has Data

queryly data query MyDB
SQL> SELECT COUNT(*) FROM users;

Check for Case Sensitivity Table names might be case-sensitive:

# Try different cases
queryly data browse MyDB Users
queryly data browse MyDB USERS
queryly data browse MyDB users

Use Query Mode to Debug

queryly data query MyDB
SQL> SELECT * FROM users LIMIT 10;

Export Fails

Problem: Export command fails or produces an empty file.Symptoms:

$ queryly data export MyDB users csv
✗ Export failed: Access denied

Solutions:

Check Write Permissions Ensure you have write access to the current directory:

# Check current directory
pwd

# Check permissions
ls -ld .

# Try exporting to a different directory
cd ~/Documents
queryly data export MyDB users csv

Verify Table Name
```
queryly schema list MyDB
```
Ensure the table name is correct (case-sensitive).
Check Table Has Data
```
queryly data browse MyDB users
```
If the table is empty, export will create an empty file.
Check Disk Space
```
# Check available space
df -h .
```
Try Different Format If CSV fails, try JSON:
```
queryly data export MyDB users json
```

Query Issues

Query Mode Freezes

Problem: Interactive query mode becomes unresponsive.Solutions:

Exit with Ctrl+C Press Ctrl+C to force exit.
Check for Long-Running Query If you ran a complex query, it might be processing. Wait or cancel with Ctrl+C.

Simplify Query Break complex queries into smaller parts:

-- Instead of a complex JOIN, start simple
SQL> SELECT * FROM users LIMIT 10;

SQL Syntax Error

Problem: Your query returns a syntax error.Solutions:

Check SQL Dialect Different databases have different syntax:
-- Use LIMIT SELECT * FROM users LIMIT 10;

Quote Table/Column Names If names contain spaces or special characters:

-- SQLite/PostgreSQL
SELECT * FROM "user data";

-- SQL Server
SELECT * FROM [user data];

-- MySQL
SELECT * FROM `user data`;

Test in Native Client First Verify the query works in the database’s native client before using Queryly.

Configuration Issues

Configuration File Corrupted

Problem: Queryly won’t start due to corrupted configuration.Solutions:

Validate JSON

# Check for JSON errors
cat ~/.queryly/connections.json

Backup and Reset

# Backup existing config
cp ~/.queryly/connections.json ~/.queryly/connections.backup.json

# Remove corrupted file
rm ~/.queryly/connections.json

# Queryly will create a fresh one on next run

Manually Fix JSON Common issues:
- Missing commas between objects
- Trailing commas
- Unescaped quotes in strings
Use a JSON validator: https://jsonlint.com/

Lost Connections After Update

Problem: Connections disappeared after updating Queryly.Solutions:

Check Backup
```
ls -la ~/.queryly/
```
Look for connections.backup.json or similar.

Restore from Backup

cp ~/.queryly/connections.backup.json ~/.queryly/connections.json

Manually Recreate If no backup exists, re-add connections:
```
queryly connect add
```

Platform-Specific Issues

Windows: Path Not Found

Problem: SQLite database path not found on Windows.Solutions:

Use Forward Slashes
```
Data Source=C:/Users/username/mydb.db
```

Or Use Double Backslashes

Data Source=C:\\Users\\username\\mydb.db

Use Relative Path
```
Data Source=./mydb.db
```

macOS: Permission Denied

Problem: Permission denied errors on macOS.Solutions:

Check File Permissions
```
ls -l mydb.db
chmod 644 mydb.db
```
Grant Full Disk Access System Preferences → Security & Privacy → Privacy → Full Disk Access → Add Terminal

Linux: Library Not Found

Problem: Missing library errors on Linux.Solutions:

Install Required Libraries

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install libicu-dev

# Fedora/RHEL
sudo dnf install icu

Install Database Client Libraries
sudo apt-get install libpq-dev

Performance Issues

Slow Query Execution

Problem: Queries take too long to execute.Solutions:

Add LIMIT Clause
```
SELECT * FROM large_table LIMIT 100;
```
Check Database Indexes Ensure proper indexes exist on frequently queried columns.
Use Browse Instead of Query For simple table viewing, browse is optimized:
```
queryly data browse MyDB large_table
```

Large Export Times Out

Problem: Exporting large tables fails or times out.Solutions:

Export in Batches Use query mode to export specific ranges:
```
SQL> SELECT * FROM large_table WHERE id BETWEEN 1 AND 10000;
```
Then export the results.

Use Native Database Tools For very large exports, use database-specific tools:

# SQLite
sqlite3 mydb.db ".mode csv" ".output data.csv" "SELECT * FROM table;"

# PostgreSQL
psql -d mydb -c "COPY table TO '/tmp/data.csv' CSV HEADER;"

# MySQL
mysql -e "SELECT * FROM table INTO OUTFILE '/tmp/data.csv'"

Getting Help

If you’re still experiencing issues:

Report Issues: Open an issue on GitHub with:

Error message (full text)
Queryly version
Operating system
Database type and version
Steps to reproduce

Community Support: Connect with other users:

GitHub Discussions
Stack Overflow (tag: queryly)

Check Logs: Enable verbose logging if available to see detailed error information.

Next Steps

Configuration Guide - Learn about configuration options
Usage Examples - See working examples
Command Reference - Explore all commands

Get Started

Commands

Database Providers

Guides

Development

Troubleshooting Guide

Common Issues

Connection Issues

Installation Issues

Schema and Data Issues

Query Issues

Configuration Issues

Platform-Specific Issues

Performance Issues

Getting Help

Next Steps

Build docs developers (and LLMs) love

Get Started

Commands

Database Providers

Guides

Development

​Common Issues

​Connection Issues

​Installation Issues

​Schema and Data Issues

​Query Issues

​Configuration Issues

​Platform-Specific Issues

​Performance Issues

​Getting Help

​Next Steps

Build docs developers (and LLMs) love

Common Issues

Connection Issues

Installation Issues

Schema and Data Issues

Query Issues

Configuration Issues

Platform-Specific Issues

Performance Issues

Getting Help

Next Steps