Troubleshooting

This guide covers common errors you may encounter when using the Tektii CLI and how to resolve them.

Command Not Found

If you see tektii: command not found after installation, the CLI is not in your PATH.

Check Installation Location

# Find where tektii was installed
which tektii
# or
ls ~/.local/bin/tektii

Add to PATH

Add the installation directory to your PATH:

# For bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify Fix

tektii --version

Authentication Errors

"API key not found"

The CLI couldn't find your API key. Make sure either:

1. The TEKTII_API_KEY environment variable is set:

# Check if set
echo $TEKTII_API_KEY

# Set it
export TEKTII_API_KEY="your-api-key"

2. Or you're passing the --api-key flag:

tektii --api-key "your-api-key" strategy list

"Invalid API key"

Your API key may be expired, revoked, or incorrectly copied. Try:

1. Create a new API key in Settings → API Keys
2. Make sure you copied the entire key
3. Check there are no extra spaces or quotes around the key

# Correct
export TEKTII_API_KEY="tk_abc123def456"

# Wrong - extra quotes inside
export TEKTII_API_KEY="'tk_abc123def456'"

Network Errors

"Connection refused"

The CLI can't reach the API server:

1. Check your internet connection
2. Verify the --api-url setting is correct (default: https://api.tektii.com)
3. Check if a firewall or proxy is blocking the connection

# Test connectivity
curl -I https://api.tektii.com/health

Timeout Errors

If commands hang or timeout:

1. Check your network speed and stability
2. Try again - temporary network issues are common
3. For large downloads, ensure sufficient disk space

Docker Issues

When using tektii version upload, you may encounter Docker-related errors.

"Docker not running"

The Docker daemon must be running for version uploads:

# macOS - start Docker Desktop
open -a Docker

# Linux - start Docker service
sudo systemctl start docker

# Verify Docker is running
docker info

Platform Mismatch (Apple Silicon)

If you see Image platform mismatch (expected linux/amd64, got darwin/arm64):

The Tektii engine runs on Cloud Run, which requires linux/amd64 images. On Apple Silicon Macs (M1/M2/M3/M4), you need to build for the correct platform.

Option 1: Enable Rosetta in Docker Desktop

1. Open Docker Desktop → Settings → General
2. Enable "Use Rosetta for x86/amd64 emulation"
3. Restart Docker Desktop

Option 2: Use Docker Buildx

# Create and use a buildx builder
docker buildx create --use

# Build with explicit platform
docker buildx build --platform linux/amd64 -t my-image .

"Failed to detect git SHA"

The CLI auto-detects your git commit SHA for version tagging. If detection fails:

# Check you're in a git repository
git status

# If not, specify the SHA manually
tektii version upload strat_abc123 --git-sha abc1234

If you're not using git, the CLI falls back to a timestamp-based tag: ts-1234567890.

Configuration Errors

"Failed to parse configuration file"

Your JSON configuration file has a syntax error:

# Validate JSON syntax
jq . config.json

# Common issues:
# - Trailing commas
# - Missing quotes around strings
# - Unescaped special characters

Debugging

Use verbose flags to see detailed output and diagnose issues.

Verbosity Levels

Examples

# Info level - see what's happening
tektii -v strategy list

# Debug level - troubleshoot issues
tektii -vv version upload strat_abc123

# Trace level - deep debugging
tektii -vvv scenario download strat_abc123 scen_def456

Still Stuck?

If you've tried the above solutions and still have issues:

1. Run your command with -vv and note the full error message
2. Check you're using the latest CLI version: tektii --version
3. Search or open an issue on our GitHub repository

Next Steps

• Installation - Reinstall if needed
• Authentication - Configure your API key