HANA CLI

Appearance

Troubleshooting Guide ​

Common issues and solutions for the MCP Server.

Connection Issues ​

Zero Results from List Commands ​

Symptom: Commands like hana_tables, hana_schemas, hana_inspectTable return empty results.

Root Cause: Missing or invalid database connection configuration.

Solution:

  1. Verify Connection Status

    bash
    hana-cli status

    Should display your connection details, current schema, and HANA version.

  2. Check default-env.json Exists

    bash
    ls -la default-env.json

    If missing, create it using:

    bash
    hana-cli connect
# or
hana-cli serviceKey -i <instance-name> -k <key-name>

  3. Validate Connection Credentials

    json
    {
  "VCAP_SERVICES": {
    "hana": [{
      "name": "my-hana-instance",
      "tags": ["hana"],
      "credentials": {
        "host": "your-host.hanacloud.ondemand.com",
        "port": "443",
        "user": "DBADMIN",
        "password": "YourPassword123!",
        "encrypt": true,
        "sslValidateCertificate": true
      }
    }]
  }
}

  4. Enable Debug Mode

    bash
    hana-cli tables --debug

    Shows connection details, query execution, and timing.

  5. Test Basic Connectivity

    bash
    # For HANA Cloud
ping your-host.hanacloud.ondemand.com

# Check port accessibility
telnet your-host.hanacloud.ondemand.com 443

Connection Timeout ​

Symptom: Commands fail with "Connection timeout" error after waiting.

Causes:

  • Network connectivity issues
  • Firewall blocking the connection
  • Database instance not running or unresponsive
  • Query too large or complex

Solutions:

  1. Verify Network Connectivity

    bash
    ping your-host.com
telnet your-host.com 443

  2. Check Database is Running

    bash
    hana-cli status

    If this fails, the database instance is not running.

  3. Increase Timeout Value

    bash
    hana-cli tables --timeout 600

    Increases timeout to 10 minutes (default 5 minutes).

  4. Filter Large Result Sets

    bash
    # Instead of listing all tables
hana-cli tables --table MY_* --schema SALES

# Instead of loading entire table
hana-cli sql "SELECT * FROM MY_TABLE LIMIT 1000"

  5. Check System Health

    bash
    hana-cli healthCheck
hana-cli memoryAnalysis

Authentication Failed ​

Symptom: "Authentication failed" or "Invalid credentials" error.

Causes:

  • Wrong username or password
  • User account disabled or expired
  • Insufficient database privileges

Solutions:

  1. Verify Credentials

    bash
    hana-cli status --user DBADMIN --password YourPassword

  2. Check User Account

    • Log in to SAP HANA database directly
    • Verify user account exists and is active
    • Check user privileges (SELECT, INSERT, UPDATE, DELETE)

  3. Reset Password

    • In SAP HANA Studio: User → Change Password
    • Or via SQL: ALTER USER <username> PASSWORD <newpassword> FORCE PASSWORD CHANGE

  4. For SAP BTP

    • Get fresh service key: hana-cli serviceKey -i <instance> -k <key>
    • Credentials may have expired after service key rotation

SSL Certificate Errors ​

Symptom: "DEPTH_ZERO_SELF_SIGNED_CERT" or "Certificate verification failed"

Causes:

  • Self-signed certificates (common in development)
  • Expired certificates
  • Certificate not trusted by system

Solutions:

  1. Temporary Fix (Development Only)

    json
    {
  "sslValidateCertificate": false
}

    ⚠️ Never do this in production!

  2. Permanent Fix

    • Update Node.js to latest version
    • Install proper SSL certificates
    • Contact database administrator

  3. System Time Issues

    • Incorrect system clock causes certificate validation failure
    • Verify system time: date
    • Sync time if needed

Command Execution Issues ​

Table Not Found Error ​

Symptom: Error: Table 'MY_TABLE' not found or Table does not exist

Causes:

  • Table name is case-sensitive (usually uppercase in HANA)
  • Table in different schema than expected
  • Table doesn't exist yet
  • User doesn't have permission to access table

Solutions:

  1. Check Table Name (Case-Sensitive)

    bash
    # These are different
MY_TABLE    # Case as stored
my_table    # Lowercase not found
My_Table    # Different case

  2. List Available Tables

    bash
    hana-cli tables
# or for specific schema
hana-cli tables --schema SALES

  3. Verify Schema

    bash
    # Check current schema
hana-cli status

# List all schemas
hana-cli schemas

# Use fully qualified name
hana-cli inspectTable --table MY_TABLE --schema SALES

  4. Check User Permissions

    bash
    # See current user
hana-cli inspectUser

# Request table access from database administrator

Schema Not Found or Not Accessible ​

Symptom: Error: Schema '<schema>' does not exist or permission denied

Causes:

  • Schema name typo or wrong case
  • User doesn't have access to schema
  • Schema doesn't exist

Solutions:

  1. List Available Schemas

    bash
    hana-cli schemas

  2. Check Schema Permissions

    bash
    hana-cli status
# Shows user and roles

  3. Request Access

    • Contact database administrator
    • Ask to grant SELECT privilege on schema
    • May need role assignment

File Not Found (Import/Export) ​

Symptom: Error: File not found or Cannot read file

Causes:

  • File path doesn't exist
  • Relative path not working as expected
  • File permissions issue
  • Wrong file format

Solutions:

  1. Verify File Path

    bash
    # Use absolute path
hana-cli import --file /absolute/path/to/data.csv

# or in current directory
ls -la data.csv

  2. Check File Exists and is Readable

    bash
    # Verify file exists
test -f data.csv && echo "File exists" || echo "Not found"

# Check permissions
ls -la data.csv
# Should show -rw- (readable)

  3. Verify File Format

    bash
    # CSV file
file -b data.csv
# Should show: ASCII text

# Excel file
file -b data.xlsx
# Should show: Microsoft Excel

  4. Check File Contents

    bash
    # Show first few lines
head -5 data.csv

# Check for encoding issues
file data.csv

Import Errors and Data Issues ​

Symptom: Import partially succeeds with some rows having errors.

Causes:

  • Data type mismatches
  • Invalid values for columns
  • Constraint violations (primary key, foreign key)
  • File format issues

Solutions:

  1. Preview Before Importing

    bash
    hana-cli import --file data.csv --table MY_TABLE --dryRun true

    Shows what would be imported without actually importing.

  2. Skip Errors and Continue

    bash
    hana-cli import \
  --file data.csv \
  --table MY_TABLE \
  --skipWithErrors true \
  --errorLimit 100

  3. Enable Error Logging

    bash
    hana-cli import \
  --file data.csv \
  --table MY_TABLE \
  --saveErrors true \
  --errorFile error.log

  4. Validate Data Quality

    bash
    # After import
hana-cli dataValidator --table MY_TABLE

# Check for duplicates
hana-cli duplicateDetection --table MY_TABLE

# Profile the data
hana-cli dataProfile --table MY_TABLE

  5. Fix Data Issues

    • Correct invalid data in source file
    • Verify column mappings
    • Check data types match table definition
    • Review constraints

Performance Issues ​

Commands Running Slow ​

Symptom: Commands take longer than expected to complete.

Causes:

  • Large datasets being processed
  • Complex queries
  • Network latency
  • Database load/contention
  • Missing indexes

Solutions:

  1. Check System Health

    bash
    hana-cli healthCheck
hana-cli memoryAnalysis

  2. Filter Large Results

    bash
    # Instead of full table
hana-cli dataProfile --table BIG_TABLE --limit 10000

# Use schema filter
hana-cli tables --schema SALES

  3. Check CPU and Memory

    bash
    hana-cli cpuAnalysis
hana-cli memoryAnalysis --sort used

  4. Identify Expensive Queries

    bash
    hana-cli expensiveStatements --order executionTime --limit 10

  5. Review Indexes

    bash
    hana-cli indexTest --table MY_TABLE

Out of Memory Error ​

Symptom: Error: Out of memory or process crashes.

Causes:

  • Processing too much data at once
  • Memory fragmentation
  • Database memory pressure

Solutions:

  1. Check Available Memory

    bash
    hana-cli memoryAnalysis
hana-cli diskSpace

  2. Process Data in Batches

    bash
    hana-cli import \
  --file large_file.csv \
  --table MY_TABLE \
  --parallel 4 \
  --batchSize 1000

  3. Increase Available Memory

    bash
    export NODE_OPTIONS="--max-old-space-size=4096"
hana-cli dataProfile --table BIG_TABLE

  4. Use Limits and Filters

    bash
    # Profile subset only
hana-cli dataProfile --table BIG_TABLE --limit 100000

MCP Server Issues ​

MCP Server Not Starting ​

Symptom: Claude Dev can't connect to MCP Server or "Connection refused"

Causes:

  • Build not updated
  • Wrong path in configuration
  • Node.js not installed
  • Port conflicts

Solutions:

  1. Rebuild MCP Server

    bash
    cd mcp-server
npm run build

  2. Verify Configuration Path

    json
    {
  "mcpServers": {
    "hana-cli": {
      "command": "node",
      "args": ["D:/projects/hana-developer-cli-tool-example/mcp-server/build/index.js"]
    }
  }
}

    Use absolute path with forward slashes.

  3. Test Server Start

    bash
    node mcp-server/build/index.js

    Should start without errors.

  4. Check Node.js Installation

    bash
    node --version
# Should be v14 or higher

No Commands Available in MCP ​

Symptom: MCP connects but shows no available commands.

Causes:

  • Build failed silently
  • TypeScript compilation errors
  • Missing dependencies

Solutions:

  1. Check Build Success

    bash
    ls -la mcp-server/build/
# Should show many files

  2. Check for Compilation Errors

    bash
    cd mcp-server
npm run build 2>&1 | tee build.log
cat build.log | grep -i error

  3. Reinstall Dependencies

    bash
    cd mcp-server
rm -rf node_modules package-lock.json
npm install
npm run build

MCP Commands Time Out ​

Symptom: "Command timeout" when running MCP tools.

Causes:

  • Database query taking too long
  • Network latency
  • Default timeout too short

Solutions:

  1. Increase Timeout

    bash
    hana-cli tables --timeout 600

  2. Filter Results

    bash
    hana-cli tables --table MY_* --schema SALES

  3. Check Database Health

    bash
    hana-cli healthCheck

Getting Help ​

Enable Debug Output ​

All commands support debug mode:

bash
hana-cli <command> --debug

Check Logs ​

bash
# View recent logs
tail -100 ~/.hana-cli/logs/latest.log

# Enable verbose logging
export DEBUG=hana-cli:*
hana-cli <command>

Community Support ​

  1. GitHub Issues

  2. SAP Community

    • SAP HANA Cloud forum
    • SAP BTP community

  3. Documentation

Troubleshooting Checklist ​

When reporting issues, include:

  • [ ] Error message (full text)
  • [ ] Command that failed
  • [ ] Debug output (--debug flag)
  • [ ] Operating system and Node.js version
  • [ ] MCP Server version
  • [ ] Connection details (host, port, schema)
  • [ ] Database version
  • [ ] Steps to reproduce

Next Steps ​