Troubleshooting

This guide helps you diagnose and resolve common issues with Kassie.

Connection Issues

Cannot connect to host

Error message:

Error: failed to connect: dial tcp 127.0.0.1:9042: connect: connection refused

Causes and solutions:

Cassandra/ScyllaDB not running

bash

# Check if service is running
systemctl status cassandra
# or
docker ps | grep scylla

Wrong host or port
- Verify host in config: ~/.config/kassie/config.json
- Default CQL port is 9042
- Check database logs for actual port

Firewall blocking connection

bash

# Test connectivity
telnet 127.0.0.1 9042
# or
nc -zv 127.0.0.1 9042

Database bound to different interface
bash
```
# Check listening addresses
netstat -tlnp | grep 9042
```
Update database config to bind to 0.0.0.0 or specific IP.

Authentication failed

Error message:

Error: authentication failed: Bad credentials

Solutions:

Verify credentials

json

{
  "auth": {
    "username": "cassandra",
    "password": "cassandra"
  }
}

Check environment variables

bash

# If using ${VAR_NAME} syntax
echo $CASSANDRA_PASSWORD

Test credentials with cqlsh

bash

cqlsh -u cassandra -p cassandra 127.0.0.1 9042

Reset Cassandra password

bash

# Default superuser
cqlsh -u cassandra -p cassandra
ALTER USER cassandra WITH PASSWORD 'new_password';

SSL/TLS connection failed

Error message:

Error: TLS handshake failed: certificate verify failed

Solutions:

Verify SSL is enabled on database
- Check Cassandra/ScyllaDB config
- Ensure client_encryption_options.enabled: true

Check certificate paths

json

{
  "ssl": {
    "enabled": true,
    "cert_path": "/path/to/client.crt",
    "key_path": "/path/to/client.key",
    "ca_path": "/path/to/ca.crt"
  }
}

Verify certificate files exist and are readable

bash

ls -l /path/to/*.crt /path/to/*.key
chmod 600 /path/to/client.key

Test SSL connection

bash

openssl s_client -connect 127.0.0.1:9042 -CAfile ca.crt

Connection timeout

Error message:

Error: query timeout after 10000ms

Solutions:

Increase timeout in config
json
```
{
  "timeout_ms": 30000
}
```
Check network latency
bash
```
ping database-host
```
Verify database performance
- Check database CPU/memory usage
- Look for slow queries in database logs
- Check for compaction or repair operations

Reduce page size

json

{
  "defaults": {
    "page_size": 50
  }
}

Configuration Issues

Config file not found

Error message:

Warning: config file not found, using defaults

Expected behavior: Kassie will use built-in defaults and try to connect to 127.0.0.1:9042.

To fix:

Create config file

bash

mkdir -p ~/.config/kassie
nano ~/.config/kassie/config.json

Use custom location

bash

kassie tui --config /path/to/config.json

Verify file exists
bash
```
ls -la ~/.config/kassie/config.json
```

Invalid JSON syntax

Error message:

Error: invalid config: unexpected token at line 5

Solutions:

Validate JSON

bash

# Use jq to validate
jq . ~/.config/kassie/config.json

Common JSON errors
- Missing comma between fields
- Trailing comma at end of array/object
- Unescaped quotes in strings
- Missing closing brace/bracket

Example valid JSON

json

{
  "version": "1.0",
  "profiles": [
    {
      "name": "local",
      "hosts": ["127.0.0.1"],
      "port": 9042
    }
  ]
}

Profile not found

Error message:

Error: profile 'production' not found in config

Solutions:

Check profile name

bash

# List all profiles
jq '.profiles[].name' ~/.config/kassie/config.json

Use correct profile name
bash
```
kassie tui --profile local
```

Add missing profile

json

{
  "profiles": [
    {
      "name": "production",
      "hosts": ["prod.example.com"],
      "port": 9042
    }
  ]
}

Environment variable not expanded

Issue: Password shows as literal ${VAR_NAME} instead of value.

Solutions:

Verify environment variable is set
bash
```
echo $CASSANDRA_PASSWORD
```

Export variable before running Kassie

bash

export CASSANDRA_PASSWORD="secret123"
kassie tui

Add to shell profile

bash

# ~/.bashrc or ~/.zshrc
export CASSANDRA_PASSWORD="secret123"
source ~/.bashrc

Query Issues

Filter syntax error

Error message:

Error: invalid filter syntax: unexpected token 'SELECT'

Solutions:

Use WHERE clause only (no SELECT, FROM, etc.)

cql

# ✓ Correct
id = '550e8400-e29b-41d4-a716-446655440000'

# ✗ Wrong
SELECT * FROM users WHERE id = '...'

Check operator support
- Supported: =, >, <, >=, <=, IN, CONTAINS
- Quote strings: status = 'active'
- Use correct syntax for IN: status IN ('active', 'pending')

Test query in cqlsh first

bash

cqlsh> SELECT * FROM keyspace.table WHERE your_filter;

Query returns no results

Issue: Filter seems correct but returns empty result set.

Debugging steps:

Remove filter and check raw data
- Press Esc to clear filter
- Verify data exists in table

Check data types

cql

# Wrong: id is UUID, not string
id = 'abc123'

# Correct: proper UUID format
id = '550e8400-e29b-41d4-a716-446655440000'

Verify partition key
- Filters must include partition key for best performance
- Check table schema to identify partition key
Check consistency level
- Try consistency: "ALL" in config for debugging

Query timeout

Error message:

Error: query timeout after 10000ms

Solutions:

Use more specific filter

cql

# Include partition key
user_id = 123 AND created_at > '2024-01-01'

Increase timeout
json
```
{
  "timeout_ms": 30000
}
```

Reduce page size

json

{
  "defaults": {
    "page_size": 50
  }
}

Check database performance
- High CPU/memory usage
- Compaction running
- Large partition warnings

Permission Errors

Insufficient permissions

Error message:

Error: Unauthorized: User does not have permission

Solutions:

Grant required permissions

cql

# As superuser
GRANT SELECT ON KEYSPACE app_data TO kassie_user;

Use correct user in config

json

{
  "auth": {
    "username": "read_only_user",
    "password": "password"
  }
}

Verify user permissions
cql
```
LIST ALL PERMISSIONS OF kassie_user;
```

Use superuser for full access (development only)

json

{
  "auth": {
    "username": "cassandra",
    "password": "cassandra"
  }
}

Performance Issues

Slow data loading

Symptoms: Data takes >5 seconds to load.

Solutions:

Reduce page size

json

{
  "defaults": {
    "page_size": 25
  }
}

Apply filters to reduce dataset

cql

partition_key = '...' AND clustering_key > '...'

Check network latency

bash

ping database-host
traceroute database-host

Monitor database performance
- Check nodetool metrics
- Review database logs
- Check for large partitions

High memory usage

Symptoms: Kassie using >500MB RAM.

Solutions:

Reduce page size (less data in memory)

json

{
  "defaults": {
    "page_size": 50
  }
}

Close inspector when not needed (TUI)
- Press Esc to close inspector
Restart Kassie periodically
- Long-running sessions may accumulate state

TUI is laggy

Solutions:

Check terminal emulator performance
- Try different terminal (e.g., Alacritty, kitty)
- Disable terminal transparency
- Reduce font size
Reduce data displayed
- Smaller page size
- Apply filters
- Close inspector

Disable features

json

{
  "clients": {
    "tui": {
      "vim_mode": false
    }
  }
}

TUI-Specific Issues

Characters look broken

Symptoms: Boxes, question marks, or garbled text.

Solutions:

Set proper locale

bash

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
kassie tui

Use UTF-8 terminal
- Check terminal settings for UTF-8 support
- Most modern terminals support UTF-8 by default
Install Unicode fonts
- Recommended: Nerd Fonts, Fira Code, JetBrains Mono

Colors are wrong

Solutions:

Set TERM variable
bash
```
export TERM=xterm-256color
kassie tui
```

Try different theme

json

{
  "clients": {
    "tui": {
      "theme": "default"
    }
  }
}

Check terminal color support

bash

# Test 256 colors
for i in {0..255}; do printf "\x1b[38;5;${i}m%03d " "$i"; done; echo

Keyboard shortcuts not working

Solutions:

Check terminal key bindings
- Some terminals intercept certain keys
- Try alternative keys (e.g., Ctrl+N instead of n)

Disable conflicting shell bindings

bash

# Temporarily disable fish vi mode
set -U fish_key_bindings fish_default_key_bindings

Use mouse as fallback (if supported)

Web UI Issues

Page won't load

Solutions:

Check server is running
bash
```
curl http://localhost:8080/health
```
Try different browser
- Clear cache and cookies
- Try incognito/private mode
Check browser console
- Press F12 → Console tab
- Look for JavaScript errors

Check port availability

bash

lsof -i :8080
# or
netstat -tlnp | grep 8080

WebSocket connection failed

Error: gRPC-Web connection error in browser console.

Solutions:

Ensure server supports HTTP/2
- Kassie server supports HTTP/2 by default
- Check for proxies that might downgrade
Check for CORS issues
- Look for CORS errors in browser console
- Kassie enables CORS by default in development
Try different port
bash
```
kassie web --port 3000
```

Slow performance

Solutions:

Enable hardware acceleration in browser settings
Reduce data displayed
- Smaller page size
- Apply filters
Close unnecessary tabs
Update browser to latest version

Debug Mode

Enable debug logging to troubleshoot issues:

bash

kassie tui --log-level debug

Log locations:

TUI: stderr (visible in terminal)
Web/Server: stdout
Docker: docker logs <container>

Debug output includes:

Connection attempts
Query execution
Response times
Error stack traces

Getting Help

If you can't resolve your issue:

Check existing issues
- GitHub Issues
- Search for your error message
Open a new issue
- Include Kassie version: kassie version
- Include error messages
- Include config (redact sensitive data)
- Include debug logs
- Describe steps to reproduce
Community support
- GitHub Discussions
- Stack Overflow (tag: kassie)

Common Error Codes

Code	Description	Common Cause
`AUTH_REQUIRED`	No token provided	Not logged in
`AUTH_INVALID`	Invalid token	Token expired or corrupted
`PROFILE_NOT_FOUND`	Profile missing	Wrong profile name
`CONNECTION_FAILED`	Can't connect	Database down or wrong host
`QUERY_ERROR`	CQL error	Invalid filter syntax
`INVALID_FILTER`	Filter syntax error	Wrong WHERE clause
`CURSOR_EXPIRED`	Pagination error	Cursor timeout (refresh)
`INTERNAL`	Server error	Check server logs

See Error Codes Reference for complete list.

Quick Fixes

Problem	Quick Fix
Can't connect	Check database is running
Auth failed	Verify username/password
Config not found	Create `~/.config/kassie/config.json`
Filter error	Use WHERE clause only
Slow loading	Reduce page size, add filters
Broken characters	`export LANG=en_US.UTF-8`
Wrong colors	`export TERM=xterm-256color`
Port in use	Use different port with `--port`

Next Steps

Configuration Guide - Review config options
TUI Usage - Learn TUI features
Contributing - Build from source for debugging

Troubleshooting ​

Connection Issues ​

Cannot connect to host ​

Authentication failed ​

SSL/TLS connection failed ​

Connection timeout ​

Configuration Issues ​

Config file not found ​

Invalid JSON syntax ​

Profile not found ​

Environment variable not expanded ​

Query Issues ​

Filter syntax error ​

Query returns no results ​

Query timeout ​

Permission Errors ​

Insufficient permissions ​

Performance Issues ​

Slow data loading ​

High memory usage ​

TUI is laggy ​

TUI-Specific Issues ​

Characters look broken ​

Colors are wrong ​

Keyboard shortcuts not working ​

Web UI Issues ​

Page won't load ​

WebSocket connection failed ​

Slow performance ​

Debug Mode ​

Getting Help ​

Common Error Codes ​

Quick Fixes ​

Next Steps ​

Troubleshooting

Connection Issues

Cannot connect to host

Authentication failed

SSL/TLS connection failed

Connection timeout

Configuration Issues

Config file not found

Invalid JSON syntax

Profile not found

Environment variable not expanded

Query Issues

Filter syntax error

Query returns no results

Query timeout

Permission Errors

Insufficient permissions

Performance Issues

Slow data loading

High memory usage

TUI is laggy

TUI-Specific Issues

Characters look broken

Colors are wrong

Keyboard shortcuts not working

Web UI Issues

Page won't load

WebSocket connection failed

Slow performance

Debug Mode

Getting Help

Common Error Codes

Quick Fixes

Next Steps