## TL;DR
A CrewAI agent hitting max iterations with "I encountered an error" is retrying a failing tool call without changing anything, usually because the tool error isnt actionable or the agent cant see the real cause. Fix it by reading the tool's raw error, making the error message specific, and adding a max-retry escape so the agent reports instead of looping.

```text
crewai 'I encountered an error' max iterations reached
```

## Use this when
- A CrewAI agent repeats "I encountered an error" until the iteration cap
- The crew makes no progress between iterations
- An agent-built crew never completes its task

## Not for this skill when
- The tool fails with a clear auth error (fix the credential, not the loop)
- The LLM itself rate-limits (thats quota, not iteration logic)
- The task definition is wrong (thats a prompt problem)

## Steps

1. Read the raw tool error, not the agent's paraphrase. Enable verbose logging:

```python
crew = Crew(agents=[agent], tasks=[task], verbose=True)
```
Expected output: the actual exception from the tool call. "I encountered an error" is the agent summarizing; the verbose log shows what really failed.

2. Make the tool's error message actionable. A tool that raises `Exception("failed")` gives the agent nothing to adapt to:

```python
raise ValueError(f"query failed: table {name} not found. Available: {tables}")
```
Expected output: the agent can now try a different table instead of retrying the same call. Vague errors are the top cause of retry loops.

3. Lower max_iter and add a fallback so failure is fast and visible:

```python
agent = Agent(max_iter=5, ...)
```
Expected output: the run fails in 5 iterations instead of 25, with the real error in the log. Long iteration budgets hide broken tools.

4. If the tool needs something the agent cant provide (a credential, a file), stop the loop with a guard in the task description:

```text
If the lookup tool errors twice, stop and report the error verbatim instead of retrying.
```
Expected output: the agent reports the blocker instead of burning iterations. This is the escape hatch for unfixable-from-inside failures.

## Variant phrasings

### agent retries the exact same tool call
The tool error gives no new information, so the agent has nothing to change. Fix the error message (step 2).

### max iterations reached with no error at all
The agent is making progress but too slowly; the task is too big for the iteration budget. Split the task or raise the budget deliberately.

## Why it happens
CrewAI agents retry failed actions up to max_iter, and each retry includes the previous error in context. When the error is unactionable, the agent cant formulate a different plan, so it retries identically until the budget runs out. The "I encountered an error" phrasing is the agent's generic wrapper; the diagnosable information is always one layer down in the tool log.

## Edge cases
- Tools with side effects (sends, writes) retried blindly can duplicate the side effect; make tools idempotent or guard retries.
- Memory of past errors is truncated in long loops; the agent may "forget" it already tried something and cycle.
- Raising max_iter on a true loop just increases cost; fix the loop, not the budget.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_TTpTc8t26f1eopYB_93LiQ