Troubleshooting

Common issues and solutions.

Provider Issues

”No LLM providers available”

Set API keys:

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="..."

Rate Limits / 429 Errors

Use built-in retry:

.withRetry({ retries: 5, minTimeout: 2000 })

Gadget Issues

Gadget Not Being Called

Improve description:

description: 'ALWAYS use this for ANY math calculation.',

Add to system prompt:

.withSystem('Use FloppyDisk to calculate disk requirements.')

Parameter Validation Failed

Add .describe() to schema:

schema: z.object({
  number: z.number().describe('Must be a number'),
})

Gadget Timeout

Increase timeout:

class SlowGadget extends Gadget({
  timeoutMs: 60000,
}) {}

// Or globally
.withDefaultGadgetTimeout(30000)

Agent Loop Issues

Agent Stuck in Loop

Increase iterations:

.withMaxIterations(20)

Add termination gadget:

class Done extends Gadget({
  description: 'Call when task is complete',
  schema: z.object({ summary: z.string() }),
}) {
  execute(params) {
    throw new TaskCompletionSignal(params.summary);
  }
}

Human Input Not Working

Register handler:

.onHumanInput(async (question) => {
  return await getUserInput(question);
})

Streaming Issues

No Output / Empty Response

Consume the stream:

// Wrong
const agent = builder.ask('prompt');

// Right
const answer = await builder.askAndCollect('prompt');

// Or
for await (const event of agent.run()) {}

Testing Issues

Mock Not Matching

Use broader matchers:

mockLLM().forAnyModel()

Mocks Persisting

Clear in beforeEach:

beforeEach(() => {
  getMockManager().clear();
});

Still Stuck?

1. Enable monitoring:

.withHooks(HookPresets.monitoring())

2. Check the Debugging Guide

3. Open an issue