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 Developers → API Keys
2. Make sure you copied the entire key
3. Check there are no extra spaces or quotes around the key

API keys are 64-character lowercase hex strings with no prefix.

# Correct
export TEKTII_API_KEY="<your-64-char-hex-key>"

# Wrong - extra quotes inside
export TEKTII_API_KEY="'<your-64-char-hex-key>'"

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 platform's scenario runner 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. Use --git-sha to provide it manually."

The CLI tags each version with your git commit SHA. This error appears only when you run version upload inside a git repository whose HEAD can't be resolved to a commit — most often a freshly initialised repo (git init) that has no commits yet:

Failed to detect git SHA. Use --git-sha to provide it manually.

Fix it by creating a commit so HEAD resolves, or by passing the SHA explicitly:

# Option 1: make an initial commit
git add -A && git commit -m "initial commit"

# Option 2: skip detection and supply a version tag yourself
tektii version upload a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d --git-sha abc1234

Skip Docker entirely with --template

First-time users can create a version from a platform template instead of building a Docker image — no Dockerfile, no registry push required.

Available templates: ma-crossover, rsi-momentum.

tektii version upload a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d --template ma-crossover

When --template is used, the CLI skips Dockerfile validation, the Docker build, and the registry push; the server copies the template image into your strategy.

Branching from an existing version with --parent

To create a new version that branches from an existing one, pass --parent:

tektii version upload a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d --parent e5f6a7b8-c9d0-4e5f-9a6b-7c8d9e0f1a2b

See the version upload reference for the full flag table.

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 a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d

# Trace level - deep debugging
tektii -vvv scenario download a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d c3d4e5f6-a7b8-4c3d-9e4f-5a6b7c8d9e0f

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. Email the full error output to support@tektii.com and we'll help you troubleshoot.

Next Steps

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