Initial commit

references/troubleshooting.md

@@ -0,0 +1,292 @@
+# SAP HANA CLI - Troubleshooting Guide
+
+**Source**: [https://github.com/SAP-samples/hana-developer-cli-tool-example](https://github.com/SAP-samples/hana-developer-cli-tool-example)
+
+Common issues, diagnostic commands, and solutions.
+
+---
+
+## Diagnostic Commands
+
+### Connection Status
+
+```bash
+hana-cli status
+```
+
+Verify current connection is active.
+
+### Privilege Error Analysis
+
+```bash
+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
+
+```bash
+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**:
+
+```bash
+# 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**:
+
+```bash
+# 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**:
+
+```bash
+# 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**:
+
+```bash
+# 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
+
+```bash
+# Check file discovery order
+ls -la default-env*.json
+ls -la .cdsrc-private.json
+ls -la .env
+```
+
+### Invalid JSON
+
+```bash
+# 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
+
+```bash
+# Reclaim storage space
+hana-cli reclaim
+```
+
+Executes:
+- `ALTER SYSTEM RECLAIM LOB SPACE`
+- `ALTER SYSTEM RECLAIM LOG`
+- `ALTER SYSTEM RECLAIM DATAVOLUME 105 DEFRAGMENT`
+
+### Check Storage
+
+```bash
+# View data volumes
+hana-cli dataVolumes
+
+# View disk info
+hana-cli disks
+```
+
+---
+
+## Debug Mode
+
+Enable debug output:
+
+```bash
+# Set DEBUG environment variable
+DEBUG=* hana-cli <command>
+
+# Or use --debug flag if available
+hana-cli <command> --debug
+```
+
+---
+
+## Reporting Issues
+
+```bash
+# 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
+
+```bash
+hana-cli --help
+hana-cli <command> --help
+```
+
+### Documentation
+
+```bash
+hana-cli readMe
+hana-cli openReadMe  # Opens in browser
+```
+
+### Changelog
+
+```bash
+hana-cli changeLog
+hana-cli openChangeLog  # Opens in browser
+```
+
+---
+
+*Reference: [https://github.com/SAP-samples/hana-developer-cli-tool-example*](https://github.com/SAP-samples/hana-developer-cli-tool-example*)