17  Troubleshooting

17.1 Common Errors

17.1.1 “Agent not found”

Agent referenced but not defined:

-- Wrong
researcher()

-- Right: Define the agent (assignment-based) first
researcher = Agent { model = "openai/gpt-4o-mini", system_prompt = "...", tools = {done} }
researcher()

17.1.2 “Provider not specified”

Agent missing a provider (or a provider-prefixed model). The simplest fix is to use model = "openai/...":

-- Wrong
worker = Agent { system_prompt = "...", tools = {done} }

-- Right
worker = Agent { model = "openai/gpt-4o-mini", system_prompt = "...", tools = {done} }

17.1.3 “Required output field missing”

Procedure didn’t return required field:

Procedure {
  output = {result = field.string{required = true}},
  function(input)
    -- Wrong: no return
    Log.info("Done")

    -- Right: return all required fields
    return {result = "completed"}
  end
}

17.1.4 “Tool ‘name’ not available”

Tool not enabled for that agent turn:

local done = require("tactus.tools.done")

search = Tool { description = "Search", input = {query = field.string{required = true}}, function(args) return "..." end }
worker = Agent { model = "openai/gpt-4o-mini", tools = {done} }
-- search exists, but worker can't call it

-- Right
worker = Agent { model = "openai/gpt-4o-mini", tools = {search, done} }

17.2 Debugging Checkpoints

View execution trace:

tactus trace-list
tactus trace-show <trace-id>

17.3 API Issues

17.3.1 Rate limits

Add delays or reduce parallelism.

17.3.2 Timeouts

Check network connectivity. Consider retry logic.

17.3.3 Invalid API key

Verify key in config or environment:

echo $OPENAI_API_KEY
cat .tactus/config.yml

17.4 Performance Issues

17.4.1 Slow execution

• Check model selection (gpt-4o-mini faster than gpt-4o)
• Review token usage
• Consider caching or Step.checkpoint(...) for expensive deterministic work

17.4.2 High costs

• Use smaller models for simple tasks
• Reduce max_tokens
• Review tool call frequency

17.5 Test Failures

17.5.1 “Step not found”

Custom step not defined or typo in step text.

17.5.2 “Specification failed”

Check that agent behavior matches spec. Run with verbose output:

tactus test procedure.tac --verbose