HANA CLI

Appearance

Troubleshooting ​

Use this guide to troubleshoot common hana-cli errors, verify fixes, and get back to work quickly. If you are just getting started, see the Installation Guide and Configuration Guide.

Common Issues & Solutions ​

Connection Issues ​

If you suspect a connection problem, start with a fast sanity check:

bash
hana-cli status
hana-cli systemInfo --output basic

Cannot Connect to Database ​

Error: Error: Cannot connect to database

Solutions:

  1. Verify credentials

    bash
    # Check default-env.json exists and is valid JSON
cat default-env.json | jq '.'

# Or check environment variables
echo $HANA_CLI_HOST $HANA_CLI_PORT $HANA_CLI_USER

    On Windows (PowerShell):

    powershell
    Get-Content .\default-env.json | ConvertFrom-Json
"$env:HANA_CLI_HOST $env:HANA_CLI_PORT $env:HANA_CLI_USER"

  2. Test network connectivity

    bash
    # Windows
ping hana.example.com

# Linux/Mac
ping -c 3 hana.example.com

  3. Verify port is correct

    • Standard SQL port: 30013 (or 30015 for cloud)
    • Check with HANA administrators

  4. Check firewall

    • Ensure port is open to your machine

Connection Timeout ​

Error: Error: Connection timeout after 30000ms

Solutions:

  1. Check network connectivity

    • Ping HANA server
    • Check for firewall rules
    • Verify proxy settings if behind corporate proxy

  2. Increase timeout

    bash
    export HANA_CONNECTION_TIMEOUT=60000  # 60 seconds
hana-cli systemInfo

    On Windows (PowerShell):

    powershell
    $env:HANA_CONNECTION_TIMEOUT = 60000
hana-cli systemInfo

  3. Check HANA service is running

    • Contact HANA administrator
    • Verify service status on HANA administrative web UI

SSL Certificate Error ​

Error: Error: self signed certificate

Solutions:

  1. For development - SSL certificate validation is disabled by default in hana-cli, so self-signed certificates should work without additional configuration.

  2. For production with trusted certificate - Use a trust store:

    Via command line when connecting:

    bash
    hana-cli connect -n host:port -u USER -p PASSWORD --trustStore /path/to/truststore.pem

    Or add to your default-env.json:

    json
    {
  "VCAP_SERVICES": {
    "hana": [{
      "credentials": {
        "host": "hana.example.com",
        "port": 30015,
        "sslTrustStore": "/path/to/truststore.pem",
        "sslValidateCertificate": true
      }
    }]
  }
}

Connection Configuration Not Found ​

Error: ❌ No Connection Configuration Found

Solutions:

  1. Check the resolution order

    • default-env-admin.json (when --admin)
    • .cdsrc-private.json (CAP cds bind)
    • .env with VCAP_SERVICES
    • --conn <file> (current or parent dirs, then ~/.hana-cli/)
    • default-env.json (current or parent dirs)
    • ~/.hana-cli/default.json (last resort)

  2. Validate the file you expect hana-cli to use

    bash
    # Check JSON validity
cat default-env.json | jq '.'

  3. If using CAP bindings

    • Ensure .cdsrc-private.json exists in the project or a parent directory
    • Run cds bind and retry the command

  4. Verify CDS bind connection

    Check if .cdsrc-private.json exists:

    bash
    # Windows
dir .cdsrc-private.json

# Linux/Mac
ls -la .cdsrc-private.json

    Validate the binding configuration:

    bash
    # Verify CDS can read the binding
cds env get requires.db.credentials

# Test the connection with hana-cli
hana-cli systemInfo --debug

    If bindings are missing or invalid:

    bash
    # Re-create bindings from Cloud Foundry
cds bind --to <service-instance-name>

# Or bind to a local configuration
cds bind --to <service-instance-name> --kind hana

Proxy or Corporate TLS Issues ​

Symptoms: TLS handshake failures, intermittent timeouts, or blocked ports

Solutions:

  1. Confirm proxy settings

    • Ensure your shell has proxy environment variables set if required by policy

  2. Test raw connectivity

    • Ping the host and verify the SQL port is reachable

  3. Use trusted certificates

    • Install the corporate CA certificate
    • Use the --trustStore option when connecting: hana-cli connect --trustStore /path/to/ca-cert.pem
    • Or add sslTrustStore to your connection configuration file

  4. Verify proxy variables

    Linux/macOS:

    bash
    echo $HTTPS_PROXY
echo $HTTP_PROXY

    Windows (PowerShell):

    powershell
    $env:HTTPS_PROXY
$env:HTTP_PROXY

Central Certificate Installation ​

Instead of adding certificates to each connection configuration, you can install them centrally for your entire environment. This approach is preferred for team/production setups as it avoids certificate duplication and makes onboarding easier.

Use the NODE_EXTRA_CA_CERTS environment variable to point Node.js to your corporate CA certificate bundle.

Windows (PowerShell):

powershell
# Set for current session only
$env:NODE_EXTRA_CA_CERTS = "C:\certs\company-ca.pem"
hana-cli systemInfo

# Set permanently (current user)
[Environment]::SetEnvironmentVariable("NODE_EXTRA_CA_CERTS", "C:\certs\company-ca.pem", "User")

# Or in Command Prompt
set NODE_EXTRA_CA_CERTS=C:\certs\company-ca.pem
hana-cli systemInfo

Linux/Mac:

bash
# Set for current session only
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/company-ca.pem
hana-cli systemInfo

# Set permanently (add to ~/.bashrc or ~/.zshrc)
echo 'export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/company-ca.pem' >> ~/.bashrc
source ~/.bashrc

Preparing your certificate file:

If you have multiple certificates or need to convert formats:

bash
# Combine multiple PEM certificates
cat cert1.pem cert2.pem > company-ca.pem

# Convert .crt to PEM
openssl x509 -inform DER -in certificate.crt -out certificate.pem

# Extract certificate from .p12/.pfx
openssl pkcs12 -in certificate.p12 -cacerts -nokeys -out certificate.pem
Option 2: Docker/Container Deployment ​

When deploying hana-cli or the included UI5 app in containers:

Dockerfile example:

dockerfile
FROM node:18

# Copy your company CA certificate
COPY company-ca.pem /etc/ssl/certs/company-ca.pem

# Set Node.js to use the certificate
ENV NODE_EXTRA_CA_CERTS=/etc/ssl/certs/company-ca.pem

# Install hana-cli
RUN npm install -g hana-cli

# Your application setup
WORKDIR /app
COPY . .
RUN npm install

# Your command here
CMD ["hana-cli", "systemInfo"]

Docker Compose example:

yaml
version: '3.8'
services:
  hana-cli:
    image: node:18
    environment:
      NODE_EXTRA_CA_CERTS: /etc/ssl/certs/company-ca.pem
      HANA_CLI_HOST: hana.example.com
      HANA_CLI_PORT: 30015
      HANA_CLI_USER: admin
      HANA_CLI_PASSWORD: password
    volumes:
      - ./company-ca.pem:/etc/ssl/certs/company-ca.pem:ro
    command: npx hana-cli systemInfo
Option 3: Corporate/Proxy Environment ​

If your organization uses a corporate proxy or firewall with certificate inspection:

bash
# 1. Get the corporate CA certificate from your IT team
# 2. Set it for Node.js (see Option 1 above)

# 3. Also configure npm if you need to install packages
npm config set cafile /path/to/company-ca.pem

# 4. Verify npm can reach the registry
npm ping

If you're behind a proxy that requires authentication:

bash
# Configure npm proxy
npm config set proxy http://username:password@proxy.company.com:8080
npm config set https-proxy http://username:password@proxy.company.com:8080

# Then set CA certificate
npm config set cafile /path/to/company-ca.pem
Reference: Certificate Configuration Options ​
MethodUse CaseScope
NODE_EXTRA_CA_CERTS env varSystem-wide, all Node.js appsAll commands, all connections
--trustStore flagSingle connection, one-off useCurrent command only
sslTrustStore in configPersistent per connectionStored in configuration file
Docker/Container volume mountContainerized deploymentsContainer environment
npm config set cafilenpm registry accessnpm operations only

See also:

Command Execution Issues ​

If a command fails unexpectedly, re-run it with debug output to capture context:

bash
hana-cli <command> --debug --verbose

On Windows (PowerShell), you can capture output to a file for sharing:

powershell
hana-cli <command> --debug --verbose | Tee-Object -FilePath hana-cli-debug.log

Command Not Found ​

Error: hana-cli: command not found

Solutions:

  1. Check available commands

    bash
    # View all available commands
hana-cli --help

  2. Review the Commands documentation

  3. Verify command spelling

    • Ensure you're using the correct command name (case-sensitive)
    • Check for typos in the command name

Permission Denied ​

Error: EACCES: permission denied

Solutions:

  1. Linux/Mac - Fix npm permissions

    bash
    mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g hana-cli

  2. Windows - Run as Administrator

    • Right-click PowerShell/CMD → Run as Administrator

  3. Use sudo (not recommended)

    bash
    sudo npm install -g hana-cli

@sap/cds-dk Not Installed (CAP Bind / CDS Features) ​

Symptoms: CAP binding errors, CDS preview failures, or messages indicating @sap/cds-dk is required

Solutions:

  1. Install the CDS Development Kit globally

    bash
    npm install -g @sap/cds-dk

  2. Verify availability

    bash
    cds --version

  3. Re-run CAP binding

    • From your CAP project root: cds bind
    • Then retry your hana-cli command

BTP CLI Missing or Not Logged In ​

Symptoms: BTP-related commands fail or return no target/global account

Solutions:

  1. Verify CLI is installed

    bash
    btp --version

  2. Login and target

    • Run btp login, then set the global account and subaccount

  3. Confirm target

    bash
    hana-cli btp

Cloud Foundry CLI Missing or Not Logged In ​

Symptoms: HANA Cloud instance queries return empty results or login errors

Solutions:

  1. Verify CLI is installed

    bash
    cf --version

  2. Login and target space

    • Run cf login and target the correct org/space

  3. Re-run the hana-cli command

    • Commands like hana-cli hc and hana-cli hdi depend on CF context

hdbsql Not Found ​

Symptoms: hana-cli hdbsql fails or hdbsql is not recognized

Solutions:

  1. Install SAP HANA Client

    • Ensure the HANA client package is installed for your OS

  2. Verify PATH

    bash
    hdbsql -version

  3. Restart your terminal

    • PATH changes often require a new shell session

Node.js Version Mismatch ​

Symptoms: startup failures, dependency install errors, or engines warnings

Solutions:

  1. Verify your Node.js version

    bash
    node --version

  2. Upgrade to the required version

    • hana-cli requires Node.js 20.19.0 or later
    • See the Installation Guide for platform-specific steps

Insufficient Privileges ​

Error: Error: Insufficient privileges for operation

Solutions:

  1. Check user permissions

    • User must have SELECT privilege on tables
    • For admin operations, use --admin flag

  2. Diagnose missing privileges

    Use the SAP HANA system procedure to identify exactly which privileges are missing:

    bash
    hana-cli callProcedure -s SYS -p GET_INSUFFICIENT_PRIVILEGE_ERROR_DETAILS --parameters GUID

    Replace GUID with the value from the original error message.

    This stored procedure will provide detailed information about missing authorizations and help guide your DBA in granting the correct privileges.

    See SAP HANA Documentation for more details.

  3. Use admin credentials

    bash
    hana-cli schemaClone -s SOURCE -t TARGET --admin

  4. Request permissions from DBA

    • Contact SAP HANA administrator
    • Provide the output from GET_INSUFFICIENT_PRIVILEGE_ERROR_DETAILS procedure
    • Ask for specific schema/table privileges

Data Import Issues ​

File Not Found ​

Error: Error: File not found: data.csv

Solutions:

  1. Use absolute path

    bash
    hana-cli import -n /full/path/to/data.csv -t TABLE

  2. Check file exists

    bash
    # Windows
dir data.csv

# Linux/Mac
ls -la data.csv

  3. Check working directory

    bash
    # Show current directory
pwd  # Linux/Mac

    Windows (PowerShell):

    powershell
    Get-Location

CSV Encoding Issues ​

Error: Error: Invalid character encoding

Solutions:

bash
# Specify encoding
hana-cli import -n data.csv -t TABLE --encoding utf-8

# Convert file encoding
iconv -f ISO-8859-1 -t UTF-8 input.csv > output.csv
hana-cli import -n output.csv -t TABLE

Column Mismatch ​

Error: Error: Column mismatch at row X

Solutions:

  1. Use name matching

    bash
    hana-cli import -n data.csv -t TABLE -m name

  2. Check column names

    bash
    hana-cli tables -s SCHEMA -t TABLE

  3. Prepare data file

    • Ensure headers match table columns
    • Use --truncate if starting fresh
    • Preview table metadata with hana-cli inspectTable --schema SCHEMA --table TABLE

Output & Format Issues ​

Output Format Error ​

Error: Error: Invalid output format

Solutions:

bash
# Use supported formats
hana-cli export -s SCHEMA -t TABLE --output json
hana-cli export -s SCHEMA -t TABLE --output csv
hana-cli export -s SCHEMA -t TABLE --output text

Large Export Timeout ​

Error: Error: Operation timeout - export too large

Solutions:

  1. Export in batches

    bash
    # Limit rows
hana-cli export -s SCHEMA -t TABLE --limit 10000 -o part1.csv

  2. Use pagination

    bash
    # Export first 1000 rows
hana-cli export -s SCHEMA -t TABLE --offset 0 --limit 1000

# Export next 1000 rows
hana-cli export -s SCHEMA -t TABLE --offset 1000 --limit 1000

  3. Filter data

    bash
    hana-cli export -s SCHEMA -t TABLE -w "STATUS='ACTIVE'" -o active.csv

Performance Issues ​

Slow Command Execution ​

Solutions:

  1. Enable debug to see timing

    bash
    hana-cli dataProfile -s SCHEMA -t TABLE --debug

  2. Check table size and access patterns

    bash
    hana-cli tableHotspots --schema SCHEMA --table TABLE

  3. Inspect expensive tables

    bash
    hana-cli inspectTable --schema SCHEMA --table TABLE

  4. Use limit for large tables

    bash
    hana-cli export -s SCHEMA -t TABLE --limit 1000

High Memory Usage ​

Solutions:

  1. Process in chunks

    bash
    hana-cli export -s SCHEMA -t TABLE --batch-size 500

  2. Increase Node.js heap

    bash
    node --max-old-space-size=4096 $(which hana-cli) export ...

    On Windows (PowerShell):

    powershell
    node --max-old-space-size=4096 (Get-Command hana-cli).Source export ...

Language & Localization ​

Wrong Language Output ​

Solution: hana-cli uses your system locale settings. Change the locale using the appropriate method for your operating system.

Windows (PowerShell):

powershell
# View current locale
[System.Globalization.CultureInfo]::CurrentCulture

# You can also check Windows system language settings
# Settings > Time & Language > Language & region

Windows (Command Prompt):

cmd
# View current locale
chcp

To change the system locale on Windows, use Settings > Time & Language > Language & region or adjust regional settings through Control Panel.

Linux/Mac:

bash
# Set for current session only
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
hana-cli systemInfo

# Set permanently (add to ~/.bashrc or ~/.zshrc)
echo 'export LANG=en_US.UTF-8' >> ~/.bashrc
echo 'export LC_ALL=en_US.UTF-8' >> ~/.bashrc
source ~/.bashrc

Available locale examples:

  • en_US.UTF-8 - English (United States)
  • de_DE.UTF-8 - German (Germany)
  • es_ES.UTF-8 - Spanish (Spain)
  • fr_FR.UTF-8 - French (France)
  • ja_JP.UTF-8 - Japanese (Japan)
  • ko_KR.UTF-8 - Korean (Korea)
  • pt_PT.UTF-8 - Portuguese (Portugal)
  • zh_CN.UTF-8 - Simplified Chinese (China)
  • hi_IN.UTF-8 - Hindi (India)
  • pl_PL.UTF-8 - Polish (Poland)

Business Application Studio (BAS) ​

This section covers troubleshooting tips specific to running hana-cli within SAP Business Application Studio (BAS), the cloud-native development environment integrated with SAP BTP.

hana-cli Not Found in BAS Terminal ​

Symptoms: Running hana-cli in the BAS integrated terminal returns "command not found" or similar error

Solutions:

  1. Install hana-cli in the workspace

    If hana-cli is not pre-installed in your BAS workspace, install it locally:

    bash
    npm install hana-cli

    Then run it via npx:

    bash
    npx hana-cli systemInfo

  2. Install globally in the dev container (if using a custom dev container)

    Edit your .devcontainer/devcontainer.json:

    json
    {
  "postCreateCommand": "npm install -g hana-cli"
}

    Then rebuild the container in VS Code.

  3. Verify the workspace has Node.js installed

    bash
    node --version
npm --version

    If Node.js is not available, request a workspace with the necessary runtime environment from your BAS administrator.

CDS Binding Not Found in BAS ​

Symptoms: Error: ❌ No Connection Configuration Found when running commands in a CAP project

Solutions:

  1. Ensure project uses cds bind (recommended)

    In your CAP project root:

    bash
    # List available service instances in your BTP subaccount
cds add hana --ucap

# Bind to a specific HANA instance
cds bind --to my-hana-service-instance

    This creates .cdsrc-private.json in your workspace with connection credentials.

  2. Verify .cdsrc-private.json exists

    bash
    # Check if the binding file exists
ls -la .cdsrc-private.json

# Validate it contains hana credentials
cat .cdsrc-private.json | jq '.requires.db.credentials'

  3. Re-bind if credentials are stale

    bash
    # Remove the old binding
rm .cdsrc-private.json

# Create a fresh binding
cds bind --to my-hana-service-instance

# Test the connection
hana-cli status

  4. Check BTP service instance is accessible

    Use BTP CLI to verify the service instance exists in your target subaccount:

    bash
    btp login
btp target --subaccount <subaccount-ID>
btp list services/instances

    If the instance is not listed, verify you have the correct subaccount targeted and the service instance hasn't been deleted.

Workspace Is Read-Only / Permission Denied Errors ​

Symptoms: EACCES: permission denied, EROFS: read-only file system, or file modification fails in BAS

Solutions:

  1. Check workspace storage quota

    In BAS, the workspace storage is limited. Run:

    bash
    # Check disk usage
df -h

# Check workspace size
du -sh ~

    If you're near quota, contact your BAS administrator to request increased storage.

  2. Verify file permissions on imported data

    If you imported CSV files or created configuration files outside BAS:

    bash
    # Check current permissions
ls -la data.csv

# Fix if needed (Linux/Mac)
chmod 644 data.csv

  3. Workspace might be locked by another session

    If multiple windows or sessions have the same workspace open:

    • Close all other editor windows/tabs for this workspace
    • Reload the current window: Press F1 → search for "Reload Window"

  4. Clear BAS cache if issues persist

    • In BAS UI, go to File → Preferences → Settings
    • Search for "Exclude Patterns" and ensure data directories are not excluded
    • Restart the workspace

BAS Workspace Timeout During Long-Running Commands ​

Symptoms: Commands time out, connection drops, or commands don't complete in BAS terminal

Solutions:

  1. Increase command timeout for long operations

    Set environment variables in the BAS terminal:

    bash
    # Increase connection timeout to 2 minutes
export HANA_CONNECTION_TIMEOUT=120000

# For export operations with large datasets
export HANA_QUERY_TIMEOUT=300000

# Then run your command
hana-cli export -s SCHEMA -t LARGE_TABLE -o output.csv

  2. Use pagination for large exports instead of single operations

    bash
    # Export in batches to avoid timeout
hana-cli export -s SCHEMA -t LARGE_TABLE --offset 0 --limit 100000 -o part1.csv
hana-cli export -s SCHEMA -t LARGE_TABLE --offset 100000 --limit 100000 -o part2.csv

  3. Keep BAS workspace active

    The workspace may suspend idle sessions:

    • Keep the terminal open and active
    • Avoid leaving long-running commands unattended for extended periods
    • Consider running large operations during off-peak hours if the system is heavily used

  4. Check BAS network connectivity

    If timeouts are frequent:

    bash
    # Test network connectivity
ping hana.example.com

# Test DNS resolution
nslookup hana.example.com

    If connectivity is unstable, contact your network/BTP administrator.

Environment Variables Not Persisting in BAS Terminal ​

Symptoms: Environment variables set in one terminal session vanish in a new tab or after closing the terminal

Solutions:

  1. Set variables persistently in .bashrc or .zshrc

    Add variables to your shell profile:

    bash
    # Open or create ~/.bashrc
cat >> ~/.bashrc << 'EOF'
export HANA_CLI_HOST=hana.example.com
export HANA_CLI_PORT=30015
export HANA_CLI_USER=myuser
EOF

# Source the file in current session
source ~/.bashrc

  2. For CAP projects, use .env file

    Create a .env file in your project root (this persists across terminal sessions):

    bash
    HANA_CLI_HOST=hana.example.com
HANA_CLI_PORT=30015
HANA_CLI_USER=myuser
HANA_CLI_PASSWORD=mypassword

    Then load it in your terminal:

    bash
    source .env
hana-cli status

  3. For BAS workspace-wide settings, use workspace settings

    Edit .vscode/settings.json in your workspace root to document environment setup (for team reference):

    json
    {
  "terminal.integrated.env.linux": {
    "HANA_CLI_HOST": "hana.example.com",
    "HANA_CLI_PORT": "30015"
  }
}

    Then set secrets / passwords separately using BAS Secrets feature.

Git / Source Control Issues in BAS when using hana-cli ​

Symptoms: Adding configuration files to Git, credential leaks, or merge conflicts with generated files

Solutions:

  1. Protect sensitive configuration files

    Add connection config files to .gitignore:

    bash
    # In your .gitignore
default-env.json
default-env-admin.json
.env
.cdsrc-private.json  # Already done by CAP
~/.hana-cli/        # Home directory configs

    Use .cdsrc-private.json for credentials (handled by CAP) or CAP's config management for secrets.

  2. Commit only non-sensitive files

    bash
    # Commit sample/template config without credentials
git add .cdsrc-template.json
git commit -m "Add sample CDS config template"

# .cdsrc-private.json with credentials is git-ignored

  3. Resolve merge conflicts in package-lock.json

    If two developers run npm install and conflict:

    bash
    npm install
git add package-lock.json
git commit -m "Resolve package-lock merge conflict"

Default HANA Connection Not Detected in CAP Project ​

Symptoms: hana-cli works outside a CAP project but fails inside, returning connection not found errors

Solutions:

  1. Verify CAP project structure

    A valid CAP project contains package.json with @sap/cds dependency and a db/ or srv/ folder:

    bash
    ls -la package.json db/ srv/

  2. Check .cdsrc-private.json is in the project root

    bash
    # Should be at project root level, not in subdirectories
ls -la .cdsrc-private.json
cat .cdsrc-private.json | jq '.requires.db.credentials'

  3. Ensure CDS finds the binding

    bash
    # Verify CDS can read the binding
cds env get requires.db

    If this returns undefined, re-run cds bind.

  4. If using a workspace with multiple projects, specify the project

    Navigate to the correct CAP project directory before running hana-cli:

    bash
    cd my-cap-project/
hana-cli systemInfo

Connection Credentials Exposed in BAS Terminal Output ​

Symptoms: Terminal history shows connection passwords, API tokens, or other credentials

Solutions:

  1. Clear terminal history

    bash
    # Clear current terminal output
clear

# Or use history management
history -c  # Clear history (bash)

  2. Use secure environment variable assignments

    Instead of typing passwords on the command line:

    bash
    # Prompt for password (not visible in history)
read -sp "Enter HANA password: " HANA_CLI_PASSWORD
export HANA_CLI_PASSWORD

# Use with hana-cli
hana-cli systemInfo

  3. Leverage BAS Secrets for credentials

    BAS provides a secure secrets management feature:

    • Access Settings → Secrets in BAS
    • Store sensitive values there instead of in files or env vars
    • Reference them in your configuration as needed

  4. Use .cdsrc-private.json instead of command-line parameters

    Credentials in files stay out of shell history:

    bash
    # Good - credentials in .cdsrc-private.json (git-ignored)
cds bind --to my-hana-service-instance
hana-cli status

# Avoid - passwords visible in command history
hana-cli status -n myhost -p mypassword

BAS and Docker / Dev Container Issues ​

Symptoms: hana-cli works on local machine but fails in BAS dev container setup, or dev container won't start

Solutions:

  1. Ensure dev container includes Node.js

    In .devcontainer/devcontainer.json:

    json
    {
  "image": "mcr.microsoft.com/devcontainers/javascript-node:18",
  "postCreateCommand": "npm install -g hana-cli @sap/cds-dk"
}

  2. Rebuild dev container after changes

    • Press F1 in BAS
    • Search for "Dev Containers: Rebuild and Reopen in Container"
    • Wait for container to rebuild

  3. Check Volume Mounts

    If workspace files aren't visible in the container:

    json
    {
  "mounts": [
    "source=${localEnv:HOME}${localEnv:USERPROFILE}/.hana-cli,target=/root/.hana-cli,type=bind"
  ]
}

  4. Forward HANA connection through BAS network

    If HANA is on a private network, ensure BAS has connectivity:

    bash
    # Inside container, test connectivity
ping hana.example.com
nc -zv hana.example.com 30015

Performance Issues in BAS ​

Symptoms: Commands run slowly, output is delayed, or UI becomes unresponsive during operations

Solutions:

  1. Check available memory and CPU in workspace

    bash
    # Check memory
free -h

# Check CPU info
nproc

  2. Limit output verbosity for large results

    bash
    # Instead of full debug output
hana-cli export -s SCHEMA -t TABLE -o data.csv

# Avoid excessive logging
hana-cli export -s SCHEMA -t TABLE -o data.csv  # without --debug

  3. Use pagination and filters to reduce data transfer

    bash
    # Reduce output size
hana-cli export -s SCHEMA -t TABLE --limit 1000 -o sample.csv

  4. Close unused editor tabs and extensions

    The BAS UI consumes resources; closing unused windows frees memory for CLI operations.

Getting Help ​

Check Documentation ​

  1. Command help

    bash
    hana-cli <command> --help

  2. Search documentation

  3. Knowledge base

    bash
    hana-cli kb search "your topic"

Enable Debug Output ​

bash
hana-cli <command> --debug --verbose

Check Logs ​

Windows (PowerShell):

powershell
# Set log level
$env:HANA_LOG_LEVEL = "debug"

# View logs
Get-Content $env:HANA_LOG_FILE

Windows (Command Prompt):

cmd
# Set log level
set HANA_LOG_LEVEL=debug

# View logs
type %HANA_LOG_FILE%

Linux/Mac:

bash
# Set log level
export HANA_LOG_LEVEL=debug

# View logs
cat $HANA_LOG_FILE

Report Issues ​

  • GitHub Issues
  • Include: error message, command executed, environment details - also consider using the command hana-cli issue to automatically gather and format information for you.

MCP Server Issues (Quick Checks) ​

If you are using the Model Context Protocol (MCP) server integration, run these quick checks first:

  1. Verify the MCP server is installed

    bash
    cd mcp-server
npm install

  2. Start the MCP server in debug mode

    bash
    npm run dev -- --debug

  3. Validate CLI connectivity separately

    bash
    hana-cli status
hana-cli systemInfo --output basic

For full MCP troubleshooting, see MCP Server Issues.

Tips & Tricks ​

Test Your Connection ​

bash
# Simple connectivity test
hana-cli systemInfo

# More detailed diagnostics
hana-cli systemInfo --debug

Dry Run ​

bash
# Most write operations support --dry-run
hana-cli import -n data.csv -t TABLE --dry-run

Batch Operations Script ​

bash
#!/bin/bash
set -e  # Exit on error

for file in data/*.csv; do
  echo "Processing $file..."
  hana-cli import -n "$file" -t TABLE || echo "Failed: $file"
done

See Also ​