salesforce QUERY_TIMEOUT when the agent's SOQL pulls too many leads without paging

TL;DR

Every wait needs a deadline and every deadline needs a next step. Set explicit timeouts on external calls, treat a timeout as 'unknown outcome' (not failure), and reconcile before retrying anything with side effects.

The query

salesforce QUERY_TIMEOUT when the agent's SOQL pulls too many leads without paging

Use this when

• calls hang indefinitely, watchdogs kill long runs, or steps stall with no error
• a timeout was followed by a duplicate or a lost action

Not for

• rate-limit 429s (the server answered; you are just going too fast)
• auth expiry mid-run (the credential died, not the network)

Steps

Step 1: Put explicit timeouts on every external call

Find the call that hung and give it a deadline: HTTP timeouts, page-load timeouts, pod startup deadlines. No call should be able to wait forever; the default in most clients is infinity, which is how 'stuck' happens.

**Expected: every external call has a named timeout; nothing can hang indefinitely.

Step 2: Treat timeout as unknown, not failed

A timed-out request may have succeeded server-side. Before retrying, check whether the effect happened (query the record, check the provider dashboard). Retrying a timed-out send blindly is how duplicates are born.

**Expected: a reconcile-before-retry step exists for every side-effecting call.

Step 3: Define what happens at the deadline

Each timeout needs a next step wired in advance: retry with backoff, skip and queue for later, escalate to a human, or fail the batch loudly. A timeout with no handler is just a slower crash.

**Expected: every timeout maps to a documented next action; nothing silently stalls.

Step 4: Break long runs into checkpointed chunks

Runs that exceed watchdogs or context limits should process in bounded batches with a checkpoint between each. A 10-hour run is ten 1-hour runs with resume points.

**Expected: killing the run at any point loses at most one batch of work.

Step 5: Alert on duration, not just on failure

Track p95 duration per step and alert when a step exceeds its budget. Timeouts you see coming are incidents you prevent; the alert is the early warning.

**Expected: a duration alert fires before the watchdog kills the run.

Why it happens

Timeouts are the absence of a decision: the agent waits, the wait has no bound, and the run dies by watchdog or human impatience. The deeper bug is treating 'no response' as 'nothing happened', which corrupts retries.

Edge cases

• Aggressive timeouts on slow-but-working endpoints create false failures; size them from p99 data.
• A timeout followed by a blind retry of a send duplicates it; always reconcile first.
• Pods 'stuck in pending' are usually resource quotas, not timeouts; check events before tuning.

Finding this skill

This skill was written for sales-outreach (SDR) agents hitting the failure above. Search Vectle for the exact error text or symptom to find it and related skills.

Provenance

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