TELA-CLI Troubleshooting

Common issues, solutions, and debugging techniques for TELA-CLI problems.

Installation Issues

Command Not Found

Problem: tela-cli: command not found

Solutions:

Check Go Installation:

go version
# Should show Go 1.19+

Verify Go PATH:

echo $PATH | grep $(go env GOPATH)/bin
# Should include Go bin directory

Add Go bin to PATH:

# Linux/macOS (add to ~/.bashrc or ~/.zshrc)
export PATH=$PATH:$(go env GOPATH)/bin
 
# Windows (PowerShell)
$env:PATH += ";$(go env GOPATH)\bin"

Reinstall TELA-CLI:

go install github.com/civilware/tela/cmd/tela-cli@latest

Permission Denied

Problem: permission denied: ./tela-cli

Solutions:

# Make executable (Linux/macOS)
chmod +x tela-cli
 
# Run with explicit path
./tela-cli
 
# Or move to system PATH
sudo mv tela-cli /usr/local/bin/

Build Failures

Problem: Build errors during compilation

Common Solutions:

Update Go:

# Check version
go version
 
# Update if needed (download from golang.org)

Clear Module Cache:

go clean -modcache
go mod tidy
go build .

Check Dependencies:

# In tela/cmd/tela-cli directory
go mod verify
go mod download

Connection Issues

Daemon Connection Failed

Problem: ❌ Error: no daemon connection

Diagnostic Steps:

Check Daemon Status:

# Test if daemon is running
curl -X POST http://127.0.0.1:10102/json_rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"DERO.GetInfo"}'

Verify Network Settings:

# In TELA-CLI
info
# Check endpoint and network configuration

Try Different Endpoints:

# Try different networks
endpoint simulator    # 127.0.0.1:20000
endpoint testnet      # 127.0.0.1:40402
endpoint mainnet      # 127.0.0.1:10102
endpoint remote       # node.derofoundation.org:11012

Solutions:

Start Local Daemon:

# For simulator (easiest for testing)
derod --simulator
 
# For testnet
derod --testnet
 
# For mainnet  
derod

Use Remote Node:

# In TELA-CLI
endpoint remote
# Uses public DERO node

Check Firewall:

# Ensure ports are not blocked
# Default ports: 10102 (mainnet), 40402 (testnet), 20000 (simulator)

Gnomon Connection Issues

Problem: Gnomon fails to start or sync

Diagnostic Steps:

Check Prerequisites:

# Daemon must be connected first
endpoint simulator
info  # Verify daemon is online (D:▲)
 
# Then start Gnomon
gnomon start

Check Gnomon Status:

info
# Look for Gnomon status (G:▲ or G:▼)

Solutions:

Restart Gnomon:

gnomon stop
gnomon start

Full Resync:

gnomon resync
# This deletes the local database and starts fresh

Check Database Permissions:

# Ensure datashards directory is writable
ls -la ~/.local/share/tela/datashards/

Wallet Issues

Wallet Connection Failed

Problem: ❌ Error: no wallet connected

Solutions:

Check Wallet File:

# Verify file exists and is readable
ls -la ./wallet.db

Interactive Connection:

# In TELA-CLI
wallet
# Follow prompts carefully

Check Password:

# Ensure correct password
# Try connecting outside TELA-CLI first with dero-wallet-cli

Insufficient Balance

Problem: ❌ Error: insufficient balance for transaction

Solutions:

Check Balance:

# In TELA-CLI
balance

Get Test DERO (Simulator):

# Simulator provides free DERO
endpoint simulator
# Mine some blocks or use faucet

Optimize Gas Usage:

# Use smaller ring sizes
# When prompted for ringsize, use 2 instead of higher values
 
# Compress large files
file-info large-file.js  # Check size
# If >15KB, compression is recommended

Deployment Issues

File Size Errors

Problem: ❌ Error: file too large for deployment

Diagnostic:

file-info problematic-file.js
# Check actual size vs limits

Solutions:

Use Compression:

# TELA-CLI will prompt for compression during install-doc
# Choose 'y' when asked "Compress file data (y/n)?"

Use Sharding:

# For files >18KB even after compression
file-shard large-file.js
# Creates multiple shard files
 
# Deploy each shard with .shard tag
install-doc large-file-1.js  # dURL: large-file-1.tela.shard
install-doc large-file-2.js  # dURL: large-file-2.tela.shard
 
# Create INDEX with .shards tag
install-index MyApp  # dURL: myapp.tela.shards

Optimize Content:

# Minify JavaScript/CSS
# Optimize images
# Remove unnecessary content

Smart Contract Validation Errors

Problem: ❌ Error: does not parse as TELA-INDEX-1

Solutions:

Check File Type:

file-info suspicious-file.html
# Verify it's a supported type

Validate Content:

# Ensure files contain valid code
# Check for special characters that might cause issues

Test Locally First:

serve local ./project-directory
# Verify everything works locally before deploying

Search & Discovery Issues

No Search Results

Problem: Search commands return no results

Diagnostic Steps:

Check Gnomon Status:

info
# Verify Gnomon is running (G:▲)

Check Network:

# Ensure you're on the right network
info
# Try different networks
endpoint testnet
gnomon start
search all

Solutions:

Wait for Sync:

# Gnomon needs time to index
gnomon start
# Wait 5-10 minutes for initial sync
search all

Add Content Manually:

# Add specific SCIDs you know exist
gnomon add f2815b442d62a055e4bb8913167e3dbce3208f300d7006aaa3a2f127b06de29d
search scid f2815b442d62a055e4bb8913167e3dbce3208f300d7006aaa3a2f127b06de29d

Reset Database:

gnomon resync
# Complete fresh start

Search Filters Too Restrictive

Problem: Search returns fewer results than expected

Check Filters:

# Check current filter settings
search exclude view
search min-likes 0  # Reset rating filter
 
# Clear exclusions if needed
search exclude clear

Server Issues

Port Already in Use

Problem: ❌ Error: could not find open port

Solutions:

Change Port Range:

port-start 9000
# Try higher port range

Reduce Server Count:

max-servers 5
# Limit concurrent servers

Check Running Processes:

# Find what's using ports
netstat -tulpn | grep :8082
# Kill conflicting processes if safe

Server Won't Start

Problem: Servers fail to start or crash immediately

Diagnostic:

# Enable debug mode
tela-cli --debug
 
# Check system status
info
list

Solutions:

Check File Permissions:

# Ensure datashards directory is writable
ls -la $(tela.GetPath())  # If using Go API

Restart TELA-CLI:

# Clean shutdown and restart
shutdown all
exit
tela-cli

Clear Temporary Files:

# Remove any stuck temporary files
rm -rf ~/.local/share/tela/datashards/tela/*

Performance Issues

Slow Operations

Problem: Commands take too long to execute

Solutions:

Optimize Gnomon:

# Use fastsync for development
gnomon stop
tela-cli --gnomon --fastsync=true
 
# Reduce parallel blocks for remote nodes
tela-cli --gnomon --num-parallel-blocks=1

Reduce Search Scope:

page-size 5              # Smaller result pages
search min-likes 50      # Filter low-rated content

Local Daemon:

# Use local daemon instead of remote
endpoint 127.0.0.1:10102
# Instead of: endpoint remote

High Memory Usage

Problem: TELA-CLI uses too much memory

Solutions:

Limit Servers:

max-servers 5
# Reduce concurrent servers

Optimize Gnomon:

# Use fewer parallel blocks
tela-cli --num-parallel-blocks=1

Regular Cleanup:

# Shutdown unused servers
shutdown tela
# Keep only necessary servers running

Debug Mode

Enable Debug Output

# Start with debug mode
tela-cli --debug
 
# Or set environment variable
export DEBUG=true
tela-cli

Debug Information

Debug mode provides detailed information about:

Network connections and responses
Smart contract parsing steps
File processing operations
Server startup/shutdown events
Transaction construction details

Example Debug Output:

DEBUG: Connecting to daemon at 127.0.0.1:20000
DEBUG: GetSC request for SCID f2815b442d62a055e4bb8913167e3dbce3208f300d7006aaa3a2f127b06de29d
DEBUG: Parsing smart contract code (1247 bytes)
DEBUG: Found TELA-INDEX-1 v1.1.0
DEBUG: Extracting 3 DOC SCIDs
DEBUG: Creating directory: datashards/tela/myapp.tela
DEBUG: Starting HTTP server on :8082

Recovery Procedures

Complete Reset

If TELA-CLI becomes unresponsive or corrupted:

# 1. Force shutdown
pkill tela-cli  # Linux/macOS
# Or Ctrl+C / Task Manager on Windows
 
# 2. Clear temporary data
rm -rf ~/.local/share/tela/datashards/tela/*
 
# 3. Reset Gnomon database
rm -rf ~/.local/share/tela/datashards/gnomon_*
 
# 4. Restart fresh
tela-cli --simulator

Wallet Recovery

If wallet connections fail:

# 1. Test wallet outside TELA-CLI
dero-wallet-cli --wallet-file=./wallet.db
 
# 2. Verify wallet integrity
# If wallet opens in dero-wallet-cli, it should work in TELA-CLI
 
# 3. Check file permissions
ls -la ./wallet.db
 
# 4. Try different wallet if available
wallet ./backup-wallet.db

Network Recovery

If network operations fail:

# 1. Test basic connectivity
ping 127.0.0.1
 
# 2. Check daemon status
curl -X POST http://127.0.0.1:10102/json_rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"DERO.GetInfo"}'
 
# 3. Restart daemon if needed
# Stop daemon and restart with appropriate flags
 
# 4. Try alternative endpoints
endpoint remote  # Use public node

Getting Help

Built-in Help

# Show all commands
help
 
# Get application info
info
 
# Check current status
list

Log Analysis

# Enable debug mode for detailed logs
tela-cli --debug
 
# Look for specific error patterns:
# - "connection refused" = daemon not running
# - "invalid SCID" = wrong format or non-existent contract
# - "insufficient balance" = need more DERO
# - "file too large" = need compression/sharding

Community Resources

GitHub Issues: Report bugs and get help
DERO Discord: Community support and discussions
Documentation: This guide and API reference
Source Code: Review implementation details

Preventive Measures

Regular Maintenance

# Weekly maintenance routine:
 
# 1. Update TELA-CLI
go install github.com/civilware/tela/cmd/tela-cli@latest
 
# 2. Clean up old servers
shutdown all
 
# 3. Optimize Gnomon database
gnomon stop
gnomon clean simulator  # If you use simulator frequently
gnomon start
 
# 4. Check wallet balance
balance
 
# 5. Verify configuration
info

Backup Procedures

# Backup important data:
 
# 1. Wallet files
cp ./wallet.db ./wallet-backup-$(date +%Y%m%d).db
 
# 2. Configuration (if customized)
cp ~/.local/share/tela/datashards/settings.db ./settings-backup.db
 
# 3. Cloned content (if important)
cp -r ~/.local/share/tela/datashards/clone ./clone-backup

⚠️

Critical Backups

Always backup wallet files before major operations
Keep records of deployed SCIDs and TXIDs
Backup any custom configuration or scripts

Error Reference

Common Error Messages

Error Message	Cause	Solution
`invalid SCID`	Wrong SCID format	Use 64-character hex string
`no daemon connection`	Daemon not running	Start daemon or change endpoint
`no wallet connected`	Wallet not loaded	Use `wallet` command
`insufficient balance`	Not enough DERO	Get more DERO or use simulator
`file too large`	File exceeds limits	Use compression or sharding
`already exists`	Content already cloned	Normal for re-serving content
`not a TELA contract`	Invalid contract type	Verify SCID is TELA content
`permission denied`	File/directory access	Check permissions
`network timeout`	Connection issues	Check network/daemon
`invalid rating`	Rating >99	Use 0-99 rating scale

Debug Command Examples

# Test specific functionality:
 
# 1. Test daemon connection
endpoint simulator
info  # Should show D:▲
 
# 2. Test wallet connection  
wallet ./test-wallet.db
balance  # Should show balance
 
# 3. Test Gnomon
gnomon start
search all  # Should return results after sync
 
# 4. Test file operations
file-info ./test-file.html
serve local ./test-directory
 
# 5. Test deployment (simulator only)
install-doc ./simple-test.html

Performance Troubleshooting

Slow Performance

Symptoms:

Commands take long time to execute
Search results load slowly
Gnomon sync is very slow

Solutions:

Optimize Gnomon:

# Reduce parallel blocks for remote connections
gnomon stop
tela-cli --gnomon --num-parallel-blocks=1
 
# Use fastsync for development
tela-cli --gnomon --fastsync=true

Reduce Search Scope:

page-size 10             # Smaller result pages
search min-likes 70      # Filter results
search exclude add test  # Exclude test content

Use Local Daemon:

# Local daemon is much faster than remote
endpoint 127.0.0.1:10102
# Instead of: endpoint remote

High Resource Usage

Solutions:

Limit Concurrent Operations:

max-servers 5            # Reduce server limit
port-start 8090          # Use different port range

Regular Cleanup:

# Shutdown unused servers
list
shutdown <unused-server-name>
 
# Or shutdown all
shutdown all

Advanced Debugging

Enable Verbose Logging

# Start with maximum debugging
export DEBUG=true
export TELA_DEBUG=true
tela-cli --debug

Network Debugging

# Test network connectivity manually
curl -v http://127.0.0.1:10102/json_rpc
 
# Check specific DERO RPC methods
curl -X POST http://127.0.0.1:10102/json_rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"DERO.GetInfo"}'

File System Debugging

# Check datashards directory
ls -la ~/.local/share/tela/datashards/
 
# Check permissions
stat ~/.local/share/tela/datashards/
 
# Check disk space
df -h ~/.local/share/tela/

When All Else Fails

Nuclear Option: Complete Reset

# 1. Stop TELA-CLI
exit
 
# 2. Remove all TELA data
rm -rf ~/.local/share/tela/
 
# 3. Reinstall TELA-CLI
go install github.com/civilware/tela/cmd/tela-cli@latest
 
# 4. Start fresh
tela-cli --simulator

Getting Support

If you're still experiencing issues:

Gather Information:
- TELA-CLI version (tela-cli --help)
- Operating system and version
- Go version (go version)
- Error messages and debug output
- Steps to reproduce the issue
Check Resources:
- Review this troubleshooting guide
- Check the API Reference for related functions
- Search existing GitHub issues
Report Issues:
- Create detailed GitHub issues
- Include debug output and reproduction steps
- Mention your environment details

Most TELA-CLI issues are related to network connectivity, wallet access, or file permissions. The diagnostic steps above solve 90% of common problems.

This troubleshooting guide covers the most common issues you'll encounter with TELA-CLI. Keep it handy for quick reference during development!