# stella CLI - Troubleshooting Guide

**Sprint:** SPRINT_4100_0006_0006 - CLI Documentation Overhaul

## Overview

This guide covers common issues encountered when using the `stella` CLI and their solutions. Issues are categorized by functional area for easy navigation.

---

## Table of Contents

1. [Authentication Issues](#authentication-issues)
2. [Crypto Plugin Issues](#crypto-plugin-issues)
3. [Build Issues](#build-issues)
4. [Scanning Issues](#scanning-issues)
5. [Configuration Issues](#configuration-issues)
6. [Network Issues](#network-issues)
7. [Permission Issues](#permission-issues)
8. [Distribution Validation Issues](#distribution-validation-issues)

---

## Authentication Issues

### Problem: `stella auth login` fails with "Authority unreachable"

**Symptoms:**
```
$ stella auth login
❌ Error: Failed to connect to Authority
Authority URL: https://auth.stellaops.example.com
Error: Connection refused
```

**Possible Causes:**
1. Authority service is down
2. Network connectivity issues
3. Incorrect Authority URL in configuration
4. Firewall blocking connection

**Solutions:**

**Solution 1: Verify Authority URL**
```bash
# Check current Authority URL
stella config get Backend.BaseUrl

# If incorrect, set correct URL
stella config set Backend.BaseUrl https://api.stellaops.example.com

# Or set via environment variable
export STELLAOPS_BACKEND_URL="https://api.stellaops.example.com"
```

**Solution 2: Test network connectivity**
```bash
# Test if Authority is reachable
curl -v https://auth.stellaops.example.com/health

# Check DNS resolution
nslookup auth.stellaops.example.com
```

**Solution 3: Enable offline cache fallback**
```bash
# Allow offline cache fallback (uses cached tokens)
export STELLAOPS_AUTHORITY_ALLOW_OFFLINE_CACHE_FALLBACK=true
export STELLAOPS_AUTHORITY_OFFLINE_CACHE_TOLERANCE=00:30:00

stella auth login
```

**Solution 4: Use API key authentication (bypass Authority)**
```bash
# Use API key instead of interactive login
export STELLAOPS_API_KEY="sk_live_your_api_key"

stella auth whoami
# Output: Authenticated via API key
```

---

### Problem: `stella auth whoami` shows "Token expired"

**Symptoms:**
```
$ stella auth whoami
❌ Error: Token expired
Expiration: 2025-12-22T10:00:00Z
Please re-authenticate with 'stella auth login'
```

**Solution:**
```bash
# Re-authenticate
stella auth login

# Or refresh token (if supported by Authority)
stella auth refresh

# Verify authentication
stella auth whoami
```

---

### Problem: HTTP 403 "Insufficient scopes" when running admin commands

**Symptoms:**
```
$ stella admin policy export
❌ HTTP 403: Forbidden
Error: Insufficient scopes. Required: admin.policy
Your scopes: scan.read, scan.write
```

**Solution:**
```bash
# Re-authenticate to obtain admin scopes
stella auth logout
stella auth login

# Verify you have admin scopes
stella auth whoami
# Output should include: admin.policy, admin.users, admin.feeds, admin.platform

# If still missing scopes, contact your platform administrator
# to grant admin role to your account
```

---

## Crypto Plugin Issues

### Problem: `stella crypto sign --provider gost` fails with "Provider 'gost' not available"

**Symptoms:**
```
$ stella crypto sign --provider gost --file document.pdf
❌ Error: Crypto provider 'gost' not available
Available providers: default
```

**Cause:**
You are using the **International distribution** which does not include GOST plugin.

**Solution:**
```bash
# Check which distribution you have
stella --version
# Output: stella CLI version 2.1.0
# Distribution: stella-international  <-- Problem!

# Download correct distribution for Russia/CIS
wget https://releases.stella-ops.org/cli/russia/latest/stella-russia-linux-x64.tar.gz
tar -xzf stella-russia-linux-x64.tar.gz
sudo cp stella /usr/local/bin/

# Verify GOST provider is available
stella crypto providers
# Output:
# - default (.NET Crypto, BouncyCastle)
# - gost (GOST R 34.10-2012)  <-- Now available
```

---

### Problem: GOST signing fails with "CryptoPro CSP not initialized"

**Symptoms:**
```
$ stella crypto sign --provider gost --algorithm GOST12-256 --file document.pdf
❌ Error: CryptoPro CSP not initialized
Container: StellaOps-GOST-2024 not found
```

**Causes:**
1. CryptoPro CSP not installed
2. Container not created
3. Invalid provider configuration

**Solutions:**

**Solution 1: Verify CryptoPro CSP installation**
```bash
# Check if CryptoPro CSP is installed
/opt/cprocsp/bin/amd64/csptestf -absorb -alg GR3411_2012_256

# If not installed, install CryptoPro CSP
sudo ./install.sh  # From CryptoPro CSP distribution
```

**Solution 2: Create GOST container**
```bash
# Create new container
/opt/cprocsp/bin/amd64/csptest -keyset -newkeyset -container "StellaOps-GOST-2024"

# List containers
/opt/cprocsp/bin/amd64/csptest -keyset -enum_cont -verifycontext

# Update configuration to use correct container name
stella config set Crypto.Providers.Gost.CryptoProCsp.ContainerName "StellaOps-GOST-2024"
```

**Solution 3: Use OpenSSL-GOST instead (development only)**
```yaml
# appsettings.yaml
StellaOps:
  Crypto:
    Providers:
      Gost:
        CryptoProCsp:
          Enabled: false  # Disable CryptoPro CSP
        OpenSslGost:
          Enabled: true   # Use OpenSSL-GOST
```

**Warning:** OpenSSL-GOST is NOT FSTEC-certified and should only be used for development/testing.

---

### Problem: eIDAS signing fails with "TSP unreachable"

**Symptoms:**
```
$ stella crypto sign --provider eidas --algorithm ECDSA-P256-QES --file contract.pdf
❌ Error: Trust Service Provider unreachable
TSP URL: https://tsp.example.eu/api/v1/sign
HTTP Error: Connection refused
```

**Solutions:**

**Solution 1: Verify TSP URL**
```bash
# Test TSP connectivity
curl -v https://tsp.example.eu/api/v1/sign

# Update TSP URL if incorrect
stella config set Crypto.Providers.Eidas.TspClient.TspUrl "https://correct-tsp.eu/api/v1/sign"
```

**Solution 2: Check API key**
```bash
# Verify API key is set
echo $EIDAS_TSP_API_KEY

# If not set, export it
export EIDAS_TSP_API_KEY="your_api_key_here"

# Or set in configuration
stella config set Crypto.Providers.Eidas.TspClient.ApiKey "your_api_key_here"
```

**Solution 3: Use local signer for AES (not QES)**
```yaml
# For Advanced Electronic Signatures (not qualified)
StellaOps:
  Crypto:
    Providers:
      Eidas:
        TspClient:
          Enabled: false
        LocalSigner:
          Enabled: true
```

---

## Build Issues

### Problem: Build fails with "DefineConstants 'STELLAOPS_ENABLE_GOST' not defined"

**Symptoms:**
```
$ dotnet build -p:StellaOpsEnableGOST=true
error CS0103: The name 'STELLAOPS_ENABLE_GOST' does not exist in the current context
```

**Cause:**
Missing `-p:DefineConstants` flag.

**Solution:**
```bash
# Correct build command (includes both flags)
dotnet build \
  -p:StellaOpsEnableGOST=true \
  -p:DefineConstants="STELLAOPS_ENABLE_GOST"

# Or for publish:
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  -p:StellaOpsEnableGOST=true \
  -p:DefineConstants="STELLAOPS_ENABLE_GOST"
```

---

### Problem: Build succeeds but crypto plugin not available at runtime

**Symptoms:**
```
# Build appears successful
$ dotnet build -p:StellaOpsEnableGOST=true -p:DefineConstants="STELLAOPS_ENABLE_GOST"
Build succeeded.

# But plugin not available
$ ./stella crypto providers
Available providers:
- default

# GOST plugin missing!
```

**Cause:**
Plugin DLL not copied to output directory.

**Solution:**
```bash
# Use dotnet publish instead of dotnet build
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  --self-contained true \
  -p:StellaOpsEnableGOST=true \
  -p:DefineConstants="STELLAOPS_ENABLE_GOST" \
  --output dist/stella-russia-linux-x64

# Verify GOST plugin DLL is present
ls dist/stella-russia-linux-x64/*.dll | grep Gost
# Expected: StellaOps.Cli.Crypto.Gost.dll
```

---

### Problem: "GLIBC version not found" when running CLI on older Linux

**Symptoms:**
```
$ ./stella --version
./stella: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found (required by ./stella)
```

**Cause:**
CLI built with newer .NET runtime requiring newer GLIBC.

**Solution:**
```bash
# Check your GLIBC version
ldd --version
# If < 2.34, upgrade to a newer Linux distribution

# Or build with older .NET runtime (if possible)
# Or use containerized version:
docker run -it stellaops/cli:latest stella --version
```

---

## Scanning Issues

### Problem: `stella scan` fails with "Image not found"

**Symptoms:**
```
$ stella scan docker://nginx:latest
❌ Error: Image not found
Image: docker://nginx:latest
```

**Solutions:**

**Solution 1: Pull image first**
```bash
# Pull image from Docker registry
docker pull nginx:latest

# Then scan
stella scan docker://nginx:latest
```

**Solution 2: Scan local tar archive**
```bash
# Export image to tar
docker save nginx:latest -o nginx.tar

# Scan tar archive
stella scan tar://nginx.tar
```

**Solution 3: Specify registry explicitly**
```bash
# Use fully-qualified image reference
stella scan docker://docker.io/library/nginx:latest
```

---

### Problem: Scan succeeds but no vulnerabilities found (expected some)

**Symptoms:**
```
$ stella scan docker://vulnerable-app:latest
Scan complete: 0 vulnerabilities found
```

**Possible Causes:**
1. Advisory feeds not synchronized
2. Offline mode with stale data
3. VEX mode filtering vulnerabilities

**Solutions:**

**Solution 1: Refresh advisory feeds (admin)**
```bash
stella admin feeds refresh --source nvd --force
stella admin feeds refresh --source osv --force
```

**Solution 2: Check feed status**
```bash
stella admin feeds status
# Output:
# Feed         Last Sync           Status
# ────────────────────────────────────────
# NVD          2025-12-23 10:00    ✅ UP
# OSV          2025-12-23 09:45    ⚠️  STALE (12 hours old)
```

**Solution 3: Disable VEX filtering**
```bash
# Scan with VEX mode disabled
stella scan docker://vulnerable-app:latest --vex-mode disabled
```

---

## Configuration Issues

### Problem: "Configuration file not found"

**Symptoms:**
```
$ stella config show
⚠️  Warning: No configuration file found
Using default configuration
```

**Solution:**
```bash
# Create user configuration directory
mkdir -p ~/.stellaops

# Create configuration file
cat > ~/.stellaops/config.yaml <<EOF
StellaOps:
  Backend:
    BaseUrl: "https://api.stellaops.example.com"
EOF

# Verify configuration is loaded
stella config show
```

---

### Problem: Environment variables not overriding configuration

**Symptoms:**
```
$ export STELLAOPS_BACKEND_URL="https://test.example.com"
$ stella config get Backend.BaseUrl
https://api.stellaops.example.com  # Still shows old value!
```

**Cause:**
Incorrect environment variable format.

**Solution:**
```bash
# Correct environment variable format (double underscore for nested properties)
export STELLAOPS_BACKEND__BASEURL="https://test.example.com"
#                        ^^ Note: double underscore

# Verify
stella config get Backend.BaseUrl
# Output: https://test.example.com  # Now correct
```

**Environment Variable Format Rules:**
- Prefix: `STELLAOPS_`
- Nested properties: Double underscore `__`
- Array index: Double underscore + index `__0`, `__1`, etc.

**Examples:**
```bash
# Simple property
export STELLAOPS_BACKEND__BASEURL="https://api.example.com"

# Nested property
export STELLAOPS_CRYPTO__DEFAULTPROVIDER="gost"

# Array element
export STELLAOPS_CRYPTO__PROVIDERS__GOST__KEYS__0__KEYID="key1"
```

---

## Network Issues

### Problem: Timeouts when connecting to backend

**Symptoms:**
```
$ stella scan docker://nginx:latest
❌ Error: Request timeout
Backend: https://api.stellaops.example.com/api/v1/scan
Timeout: 30s
```

**Solutions:**

**Solution 1: Increase timeout**
```yaml
# appsettings.yaml
StellaOps:
  Backend:
    Http:
      TimeoutSeconds: 120  # Increase from 30 to 120
```

**Solution 2: Check network latency**
```bash
# Ping backend
ping api.stellaops.example.com

# Test HTTP latency
time curl -v https://api.stellaops.example.com/health
```

**Solution 3: Use proxy**
```bash
# Set HTTP proxy
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"

stella scan docker://nginx:latest
```

---

### Problem: SSL certificate verification fails

**Symptoms:**
```
$ stella scan docker://nginx:latest
❌ Error: SSL certificate verification failed
Certificate: CN=api.stellaops.example.com
Error: The SSL certificate is invalid
```

**Solutions:**

**Solution 1: Add CA certificate**
```bash
# Add custom CA certificate (Linux)
sudo cp custom-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# Add custom CA certificate (macOS)
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain custom-ca.crt
```

**Solution 2: Disable SSL verification (INSECURE - development only)**
```bash
# WARNING: This disables SSL verification. Use only for testing!
export STELLAOPS_BACKEND__HTTP__DISABLESSLVERIFICATION=true

stella scan docker://nginx:latest
```

---

## Permission Issues

### Problem: "Permission denied" when running `stella`

**Symptoms:**
```
$ stella --version
bash: /usr/local/bin/stella: Permission denied
```

**Solution:**
```bash
# Make binary executable
chmod +x /usr/local/bin/stella

# Verify
stella --version
```

---

### Problem: "Access denied" when accessing keys

**Symptoms:**
```
$ stella crypto sign --provider gost --file doc.pdf
❌ Error: Access denied to key file
File: /etc/stellaops/keys/gost-key.pem
```

**Solution:**
```bash
# Fix key file permissions
sudo chmod 600 /etc/stellaops/keys/gost-key.pem
sudo chown $(whoami):$(whoami) /etc/stellaops/keys/gost-key.pem

# Or run as root (not recommended)
sudo stella crypto sign --provider gost --file doc.pdf
```

---

## Distribution Validation Issues

### Problem: Validation script reports "wrong plugins included"

**Symptoms:**
```
$ ./validate-distribution.sh international dist/stella-international-linux-x64/stella
❌ FAIL: International distribution contains restricted plugins
Found: GostCryptoProvider
```

**Cause:**
Built with wrong flags or flags not working.

**Solution:**
```bash
# Clean and rebuild without regional flags
dotnet clean
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  --self-contained true \
  --output dist/stella-international-linux-x64

# Verify no build flags were set
echo "No StellaOpsEnableGOST, StellaOpsEnableEIDAS, or StellaOpsEnableSM flags"

# Re-validate
./validate-distribution.sh international dist/stella-international-linux-x64/stella
# Expected: ✅ PASS
```

---

## Diagnostic Commands

### Check CLI Version and Distribution

```bash
stella --version
# Output:
# stella CLI version 2.1.0
# Build: 2025-12-23T10:00:00Z
# Commit: dfaa207
# Distribution: stella-russia
# Platform: linux-x64
# .NET Runtime: 10.0.0
```

### System Diagnostics

```bash
stella system diagnostics
# Output:
# System Diagnostics:
# ✅ CLI version: 2.1.0
# ✅ .NET Runtime: 10.0.0
# ✅ Backend reachable: https://api.stellaops.example.com
# ✅ Authentication: Valid (expires 2025-12-24)
# ✅ Crypto providers: default, gost
# ⚠️  PostgreSQL: Not configured (offline mode)
```

### Check Available Crypto Providers

```bash
stella crypto providers --verbose
# Output:
# Available Crypto Providers:
#
# Provider: default
#   Description: .NET Crypto, BouncyCastle
#   Algorithms: ECDSA-P256, ECDSA-P384, EdDSA, RSA-2048, RSA-4096
#   Status: ✅ Healthy
#
# Provider: gost
#   Description: GOST R 34.10-2012, GOST R 34.11-2012
#   Algorithms: GOST12-256, GOST12-512, GOST2001
#   Status: ⚠️  CryptoPro CSP not initialized
```

### Verbose Mode

```bash
# Enable verbose logging for all commands
stella --verbose <command>

# Example:
stella --verbose auth login
stella --verbose scan docker://nginx:latest
stella --verbose crypto sign --provider gost --file doc.pdf
```

---

## Getting Help

If you're still experiencing issues after trying these solutions:

1. **Check Documentation:**
   - [CLI Overview](README.md)
   - [CLI Architecture](architecture.md)
   - [Command Reference](command-reference.md)
   - [Compliance Guide](compliance-guide.md)

2. **Enable Verbose Logging:**
   ```bash
   stella --verbose <command>
   ```

3. **Check GitHub Issues:**
   - https://git.stella-ops.org/stella-ops.org/git.stella-ops.org/issues

4. **Community Support:**
   - GitHub Discussions: https://github.com/stellaops/stellaops/discussions

5. **Commercial Support:**
   - Contact: support@stella-ops.org

---

## Common Error Codes

| Exit Code | Meaning | Typical Cause |
|-----------|---------|---------------|
| `0` | Success | - |
| `1` | General error | Check error message |
| `2` | Policy violations | Scan found policy violations (with `--fail-on-policy-violations`) |
| `3` | Authentication error | Token expired or invalid credentials |
| `4` | Configuration error | Invalid configuration or missing required fields |
| `5` | Network error | Backend unreachable or timeout |
| `10` | Invalid arguments | Incorrect command usage or missing required arguments |

---

## Frequently Asked Questions (FAQ)

### Q: How do I switch between crypto providers?

**A:** Use the `--provider` flag or create a crypto profile:

```bash
# Method 1: Use --provider flag
stella crypto sign --provider gost --file doc.pdf

# Method 2: Create and use profile
stella crypto profiles create my-gost --provider gost --algorithm GOST12-256
stella crypto profiles use my-gost
stella crypto sign --file doc.pdf  # Uses my-gost profile
```

### Q: Can I use multiple regional plugins in one distribution?

**A:** No. Each distribution includes only one regional plugin (GOST, eIDAS, or SM) to comply with export control laws.

### Q: How do I update the CLI?

**A:**
```bash
# If installed via .NET tool
dotnet tool update --global StellaOps.Cli

# If installed via binary download
wget https://releases.stella-ops.org/cli/latest/stella-<distribution>-<platform>.tar.gz
tar -xzf stella-<distribution>-<platform>.tar.gz
sudo cp stella /usr/local/bin/
```

### Q: How do I enable offline mode?

**A:**
```bash
# Set offline mode
export STELLAOPS_OFFLINE_MODE=true

# Create offline package (admin)
stella offline sync --output stellaops-offline-$(date +%F).tar.gz

# Load offline package in air-gapped environment
stella offline load --package stellaops-offline-2025-12-23.tar.gz
```

---

## See Also

- [CLI Overview](README.md) - Installation and quick start
- [CLI Architecture](architecture.md) - Plugin architecture
- [Command Reference](command-reference.md) - Command usage
- [Compliance Guide](compliance-guide.md) - Regional compliance
- [Distribution Matrix](distribution-matrix.md) - Build and distribution
- [Crypto Plugins](crypto-plugins.md) - Plugin development