Skip to content

Troubleshooting

Common issues and solutions for Tessera.

Installation Issues

ImportError: No module named 'tessera'

Problem: Tessera not installed or not in Python path

Solution: 

#Install from PyPI
pip install tessera-agents

# Or install from source
cd tessera
uv sync
uv run tessera --version

Command not found: tessera

Problem: CLI not in PATH

Solution: 

# Using uvx (no install needed)
uvx tessera-agents "your task"

# Or install as tool
uv tool install tessera-agents
tessera --version

Configuration Issues

No config file found

Problem: Config file not initialized

Solution: 

tessera init  # Creates ~/.config/tessera/config.yaml

Config validation failed

Problem: Invalid YAML syntax or schema

Solution: 

# Check YAML syntax
python -c "import yaml; yaml.safe_load(open('~/.config/tessera/config.yaml'))"

# Re-run init to validate
tessera init

API Key Issues

No API key found

Problem: Missing LLM provider API key

Solution: 

# Set environment variable
export OPENAI_API_KEY=sk-your-key-here

# Or use 1Password
export OP_OPENAI_ITEM=op://Private/OpenAI/credential

Invalid API key format

Problem: Key doesn't match expected format

Solution:

  • OpenAI: Must start with sk-
  • Anthropic: Must start with sk-ant-
  • GitHub Copilot: Must start with ghu_ (not ghp_)
# Generate Copilot token
npx copilot-api@latest auth

Execution Issues

Proxy failed to start

Problem: GitHub Copilot proxy won't start

Solution: 

# Verify Node.js installed
node --version  # Need v18+

# Install copilot-api
npm install -g copilot-api@latest

# Check token format
echo $GITHUB_TOKEN | cut -c1-4  # Should show: ghu_

Tasks stuck in queue

Problem: Tasks not executing

Possible Causes:

  1. Circular dependencies: Task A depends on B, B depends on A
  2. Missing agent: No agent with required capabilities
  3. API rate limit: Provider throttling requests

Solution: 

# Check session status
tessera session-list

# Review task dependencies in logs
cat ~/.local/share/tessera/traces.jsonl | jq '.attributes.task_id'

Out of memory errors

Problem: Large context windows exhaust RAM

Solution: 

# Reduce context size
agents:
  defaults:
    context_size: 4096  # Instead of 32k+

# Reduce parallel agents
workflow:
  max_parallel: 2  # Instead of 5+

Coverage & Testing Issues

Pytest runaway processes

Problem: Multiple pytest processes running

Solution:

This was fixed in v1.0.0. If you still see it:

# Kill all pytest
killall -9 Python

# Update to latest version
pip install --upgrade tessera-agents

Coverage not reaching threshold

Problem: Tests fail with coverage < 85%

Note: This is expected during development. Coverage requirement is for Tessera's own development, not your generated projects.

Cost & Token Issues

Costs higher than expected

Problem: Task using more tokens/money than anticipated

Solutions:

  1. Set cost limits: 

    cost:
  limits:
    per_task:
      max_usd: 1.00
      enforcement: "hard"

  2. Use cheaper models: 

    agents:
  definitions:
    - model: gpt-4o-mini  # Cheaper than gpt-4

  3. Reduce context: 

    agents:
  defaults:
    context_size: 4096  # Smaller context = fewer tokens

Token tracking shows 0

Problem: Token usage not being captured

Possible Causes:

  • Using provider without token extraction support
  • Callback not registered properly
  • Streaming mode (tokens counted differently)

Verification: 

# Check if provider supports token tracking
# All major providers (OpenAI, Anthropic, Copilot) supported

Slack Integration Issues

Slack client creation fails

Problem: Missing Slack tokens

Solution: 

export SLACK_BOT_TOKEN=xoxb-your-token
export SLACK_APP_TOKEN=xapp-your-token
export SLACK_AGENT_CHANNEL=C123456  # Channel ID
export SLACK_USER_CHANNEL=C789012

Messages not appearing

Problem: Bot not posting to Slack

Checks:

  1. Bot has correct scopes: chat:write, chat:write.public
  2. Bot invited to channels
  3. Channel IDs are correct (not channel names)

Performance Issues

Slow task execution

Optimizations:

# Use faster models
agents:
  definitions:
    - model: gpt-4o  # Faster than gpt-4

# Increase parallelism
workflow:
  max_parallel: 5  # More concurrent tasks

# Reduce iteration loops
workflow:
  max_iterations: 5  # Fewer retry attempts

High memory usage

Solutions:

  • Reduce max_parallel
  • Smaller context_size
  • Clear SQLite database periodically
# Clear old metrics (keeps schema)
sqlite3 ~/.local/share/tessera/metrics.db "DELETE FROM agent_performance WHERE timestamp < date('now', '-30 days')"

Memory & Workspace Issues

Memory database corrupted

Problem: Agent memory database won't load

Solution: 

# Backup existing database
cp ~/.cache/tessera/agent_memory.db ~/.cache/tessera/agent_memory.db.backup

# Remove corrupted database (will recreate on next use)
rm ~/.cache/tessera/agent_memory.db
rm ~/.cache/tessera/vector_memory.db

Workspace not found

Problem: Registered workspace missing

Solution: 

from tessera.workspace import get_workspace_manager

manager = get_workspace_manager()

# List all workspaces
for ws in manager.list_workspaces(include_archived=True):
    print(f"{ws.name}: {ws.path} (archived: {ws.archived})")

# Re-register if needed
manager.register_workspace("my_project", Path("/path/to/project"))

Sandbox permission denied

Problem: Filesystem guard blocking operations

Solution: 

from tessera.workspace import check_path_access, PathPermission
from pathlib import Path

# Debug permission issue
allowed, reason = check_path_access(
    Path("/path/to/file"),
    PathPermission.WRITE
)
print(f"Allowed: {allowed}, Reason: {reason}")

# If safe, add to allowed paths
from tessera.workspace import FilesystemGuard
guard = FilesystemGuard(workspace_root=Path.cwd())
guard.add_allowed_path(Path("/safe/directory"))

Sandbox resource limits hit

Problem: Process killed by sandbox limits

Solution: 

from tessera.workspace import Sandbox, SandboxConfig

# Increase limits for resource-intensive tasks
config = SandboxConfig(
    workspace_root=Path("/project"),
    max_memory_mb=8192,      # Increase memory
    max_cpu_time_seconds=1800,  # Increase CPU time
    max_file_size_mb=500     # Increase file size
)
sandbox = Sandbox(config)

Getting Help

Check Logs

# Enable debug logging
export TESSERA_LOG_LEVEL=DEBUG
tessera main "your task"

# Check traces
tail -f ~/.local/share/tessera/traces.jsonl | jq

Report Issues

  1. Check GitHub Issues
  2. Include:
  3. Tessera version (tessera --version)
  4. Python version (python --version)
  5. Error message and traceback
  6. Config file (remove API keys!)
  7. Steps to reproduce

Common Error Messages

"No models configured"

Add models to config: 

agents:
  definitions:
    - name: supervisor
      model: gpt-4  # ← Add this

"Dry-run mode: no execution"

Remove --dry-run flag: 

tessera main "task"  # Not: tessera main --dry-run "task"

"Vertex AI authentication failed"

# Setup Vertex AI credentials
gcloud auth application-default login
export VERTEX_PROJECT=your-project-id
export VERTEX_LOCATION=us-east5

Still Stuck?