Troubleshooting
Troubleshooting
Solutions to common problems, error codes, and performance optimization guide for Machbase.
Common Issues
Server Issues
Server Won’t Start
Symptoms:
machadmin -ufails- “Address already in use” error
- No server process running
Solutions:
# Check if port is in use
netstat -an | grep 5656
lsof -i :5656
# Check the PID and process name from lsof, then stop that service with its own management command
# To stop an existing Machbase process
machadmin -s
# Check database directory
ls -la $MACHBASE_HOME/dbs/
# Review logs
tail -50 $MACHBASE_HOME/trc/machbase.trc
# Try starting again
machadmin -uServer Crashes
Symptoms:
- Server stops unexpectedly
- Core dump files
- “Segmentation fault” errors
Solutions:
# Check logs
tail -100 $MACHBASE_HOME/trc/machbase.trc
# Check system resources
free -h
df -h
# Reduce memory usage (in machbase.conf)
# PROCESS_MAX_SIZE = 1073741824 # 1GB
# Check for disk space
du -sh $MACHBASE_HOME/dbs/Connection Issues
Cannot Connect
Symptoms:
- “Connection refused” error
- “Connection timeout”
- machsql fails to connect
Solutions:
# Verify server is running
machadmin -e
# Check network connectivity
ping server-address
telnet server-address 5656
# Check firewall
sudo iptables -L | grep 5656
# Verify credentials
machsql -s localhost -u SYS -p MANAGERToo Many Connections
Symptoms:
- “Max connections exceeded” error
- New connections rejected
Solutions:
-- Check the number of connections
SELECT COUNT(*) FROM V$SESSION;
-- Increase MAX_SESSION_COUNT in machbase.conf
-- MAX_SESSION_COUNT = 8192
-- Kill idle connections (if necessary)Query Issues
Slow Queries
Symptoms:
- Queries take too long
- Timeout errors
- High CPU usage
Solutions:
-- Add time filter
SELECT * FROM table DURATION 1 HOUR; -- Add this!
-- Use LIMIT
SELECT * FROM table LIMIT 1000;
-- Query rollup instead of raw data
SELECT ROLLUP('hour', 1, time) AS rtime, AVG(value)
FROM sensors
WHERE name = 'sensor-1'
GROUP BY rtime;
-- Create index
CREATE INDEX idx_column ON table(column);
-- Check query plan
EXPLAIN SELECT ...;Out of Memory
Symptoms:
- “Out of memory” error
- Query fails midway
- Server becomes unresponsive
Solutions:
-- Reduce result set
SELECT * FROM table DURATION 1 HOUR LIMIT 1000;
-- Select fewer columns
SELECT col1, col2 FROM table; -- Not SELECT *
-- Increase MAX_QPX_MEM in machbase.conf
-- MAX_QPX_MEM = 1GData Issues
Import Fails
Symptoms:
- machloader error
- CSV import fails
- Data type mismatch
Solutions:
# Check CSV format
head -10 data.csv
# Verify table schema
machsql -f - <<EOF
SHOW TABLE tablename;
EOF
# Check error log
cat $MACHBASE_HOME/trc/machloader.trc
# Validate data types
# Ensure CSV columns match table schema
# Try small batch first
head -100 data.csv > test.csv
machloader -i -t table -d test.csv -l /tmp/machloader.log
# Check the execution log specified with machloader -l
cat /tmp/machloader.logMissing Data
Symptoms:
- Expected data not found
- Count mismatch
- Time gaps
Solutions:
-- Check time range
SELECT MIN(_arrival_time), MAX(_arrival_time) FROM table;
-- Check total count
SELECT COUNT(*) FROM table;
-- Check for NULLs
SELECT COUNT(*) FROM table WHERE column IS NULL;
-- Verify import completed
-- Check machloader logsError Codes
Common Error Messages
The following are example messages for classifying symptoms. For the actual error number and its meaning, look up the number returned by the server in Error Codes.
| Example Message | Solution |
|---|---|
| Connection failed | Check server status, network |
| Authentication failed | Verify username/password |
| Table not found | Check table name, use SHOW TABLES |
| Column not found | Verify column name, use SHOW TABLE |
| Duplicate key | Check PRIMARY KEY constraints |
| Data type mismatch | Validate data types |
| Out of memory | Reduce query size, increase memory |
| Timeout | Add time filter, increase timeout |
For complete error code reference, see Error Codes.
Performance Optimization
Query Optimization
- Always use time filters
-- Bad
SELECT * FROM sensors WHERE sensor_id = 'sensor01';
-- Good
SELECT * FROM sensors
WHERE sensor_id = 'sensor01'
DURATION 1 HOUR;- Use rollup for analytics
-- Slow
SELECT AVG(value) FROM sensors
WHERE name = 'sensor-1'
AND time BETWEEN now - 7d AND now;
-- Fast
-- sensors must be a TAG table created WITH ROLLUP.
SELECT ROLLUP('hour', 1, time) AS rtime, AVG(value)
FROM sensors
WHERE name = 'sensor-1'
AND time BETWEEN now - 7d AND now
GROUP BY rtime;- Create indexes
CREATE INDEX idx_level ON logs(level);- Limit results
SELECT * FROM logs DURATION 1 DAY LIMIT 1000;Server Tuning
# Memory optimization
PROCESS_MAX_SIZE = 4294967296 # 4GB
MAX_QPX_MEM = 1073741824 # Per-query memory
# Performance tuning
DISK_COLUMNAR_TABLE_CHECKPOINT_INTERVAL_SEC = 900
DISK_COLUMNAR_INDEX_CHECKPOINT_INTERVAL_SEC = 900
QUERY_PARALLEL_FACTOR = 8Data Management
- Implement retention
DELETE FROM logs EXCEPT 30 DAYS;- Batch writes
# Use APPEND API for bulk inserts
# conn: connection from machbaseAPI.connect(), data: list of rows
conn.append('table', data)- Monitor storage
SHOW STORAGE;Diagnostic Commands
Check Server Status
# Server running?
machadmin -e
# View active queries
machsql -f - <<EOF
SHOW STATEMENTS;
EOF
# Check storage
machsql -f - <<EOF
SHOW STORAGE;
EOFCheck Logs
# Server log
tail -50 $MACHBASE_HOME/trc/machbase.trc
# Error log
grep -i error $MACHBASE_HOME/trc/machbase.trc
# Recent activity
tail -100 $MACHBASE_HOME/trc/machbase.trcSystem Information
-- Tables
SHOW TABLES;
-- Table details
SHOW TABLE tablename;
-- Users
SHOW USERS;
-- Indexes
SHOW INDEXES;
-- License
SHOW LICENSE;Getting Help
Information to Gather
When reporting issues, collect:
- Error message (exact text)
- Server logs ($MACHBASE_HOME/trc/machbase.trc)
- Machbase version (
machadmin -v) - Operating system (
uname -a) - Steps to reproduce
Support Resources
- Documentation: Review this guide and Common Issues
- Error Codes: Check Error Code Reference
- Memory Issues: See Memory Error Guide
Best Practices to Avoid Issues
- Always use time filters in queries
- Implement data retention policies
- Monitor server resources regularly
- Regular backups (daily)
- Test queries on small datasets first
- Use appropriate table types for data
- Keep Machbase updated to latest version
Quick Fixes
# Restart server
machadmin -s && sleep 5 && machadmin -u
# Check disk space
df -h
# Check memory
free -h
# View recent errors
grep -i error $MACHBASE_HOME/trc/machbase.trc | tail -20
# Test connection
machsql -s localhost -u SYS -p MANAGER -f - <<EOF
SELECT SYSDATE;
EOFRelated Documentation
- Configuration - Server configuration
- Tools Reference - Command-line tools
- Common Issues - Frequently asked questions
Last updated on