gh-secondsky-sap-skills-skills-sap-hana-cli/references/troubleshooting.md

SAP HANA CLI - Troubleshooting Guide

Source: https://github.com/SAP-samples/hana-developer-cli-tool-example

Common issues, diagnostic commands, and solutions.

---

Diagnostic Commands

Connection Status

hana-cli status

Verify current connection is active.

Privilege Error Analysis

hana-cli privilegeError [guid]

Aliases: pe, getInsufficientPrivilegeErrorDetails

Diagnoses specific privilege errors using the error GUID.

System Procedure: SYS.GET_INSUFFICIENT_PRIVILEGE_ERROR_DETAILS

User Inspection

hana-cli inspectUser [user]

View user metadata and privileges.

---

Common Issues

Connection Problems

Error	Cause	Solution
Connection refused	Wrong host/port	Verify hostname and port
SSL handshake failed	Certificate issue	Add --trustStore
Authentication failed	Wrong credentials	Check user/password
Connection timeout	Network issue	Check firewall rules
Host not found	DNS issue	Use IP address

Diagnostic Steps:

# 1. Check current status
hana-cli status

# 2. Test with explicit credentials
hana-cli connect -n "host:443" -u USER -p PASS --encrypt

# 3. Add trust store if needed
hana-cli connect --trustStore /path/to/cert.pem

Permission Errors

Error	Cause	Solution
Insufficient privilege	Missing role	Grant required roles
Object not found	Wrong schema	Check schema name
Access denied	Object ownership	Check privileges

Diagnostic Steps:

# 1. Get error GUID from error message
# 2. Analyze with privilegeError
hana-cli privilegeError <guid>

# 3. Check user details
hana-cli inspectUser

# 4. Review available roles
hana-cli roles

HDI Container Issues

Error	Cause	Solution
HDI not activated	Service disabled	Run activateHDI
Cannot create container	No admin rights	Get HDI admin role
Container exists	Name conflict	Use unique name
Cannot drop group	Not empty	Drop containers first

Diagnostic Steps:

# 1. Check HDI status
hana-cli containers

# 2. Verify admin rights
hana-cli adminHDI

# 3. List container users
hana-cli createContainerUsers -c CONTAINER --list

Cloud Connection Issues

Error	Cause	Solution
Instance not found	Wrong name	Verify instance name
Instance stopped	Not running	Run hanaCloudStart
Service key invalid	Expired/revoked	Regenerate key
BTP target wrong	Wrong subaccount	Reconfigure with btp

Diagnostic Steps:

# 1. Check BTP target
hana-cli btpInfo

# 2. List instances
hana-cli hanaCloudInstances

# 3. Start if stopped
hana-cli hanaCloudStart <instance>

# 4. Reconfigure BTP
hana-cli btp

---

Error Messages Reference

Connection Errors

"ECONNREFUSED"

Error: connect ECONNREFUSED 127.0.0.1:30015

Solution: Check host and port, ensure database is running.

"SSL_ERROR_SYSCALL"

Error: SSL_ERROR_SYSCALL

Solution: Enable encryption with --encrypt or add trust store.

"EHOSTUNREACH"

Error: connect EHOSTUNREACH

Solution: Check network connectivity, VPN if required.

Authentication Errors

"Invalid username or password"

Error: authentication failed

Solution: Verify credentials, check user is not locked.

"User is locked"

Error: user account is locked

Solution: Unlock user via HANA Studio or SQL.

Privilege Errors

"Insufficient privilege"

Error: insufficient privilege: Not authorized

Solution: Use privilegeError with GUID to diagnose, grant required roles.

---

Credential File Issues

Missing Credentials

# Check file discovery order
ls -la default-env*.json
ls -la .cdsrc-private.json
ls -la .env

Invalid JSON

# Validate JSON syntax
cat default-env.json | python -m json.tool

Wrong Credentials Priority

Remember the priority order:

1. default-env-admin.json (with --admin)
2. .cdsrc-private.json (cds bind)
3. .env file
4. --conn parameter
5. default-env.json
6. ~/.hana-cli/default.json

---

System Resource Issues

Reclaim Resources

# Reclaim storage space
hana-cli reclaim

Executes:

• ALTER SYSTEM RECLAIM LOB SPACE
• ALTER SYSTEM RECLAIM LOG
• ALTER SYSTEM RECLAIM DATAVOLUME 105 DEFRAGMENT

Check Storage

# View data volumes
hana-cli dataVolumes

# View disk info
hana-cli disks

---

Debug Mode

Enable debug output:

# Set DEBUG environment variable
DEBUG=* hana-cli <command>

# Or use --debug flag if available
hana-cli <command> --debug

---

Reporting Issues

# Open issue on GitHub
hana-cli issue

Opens browser to create GitHub issue with:

• Version information
• Environment details
• Steps to reproduce

---

Getting Help

In-CLI Help

hana-cli --help
hana-cli <command> --help

Documentation

hana-cli readMe
hana-cli openReadMe  # Opens in browser

Changelog

hana-cli changeLog
hana-cli openChangeLog  # Opens in browser

---

*Reference: https://github.com/SAP-samples/hana-developer-cli-tool-example*