Fix a stuck batch

A batch that stops moving is almost always waiting for a person or parked on an error. Open the batch’s Overview to see where companies are, then a parked company’s drawer to see why.

The batch won’t open

The error says	Fix
tenant <id> has no hubspot credentials; set them with PUT …	The HubSpot token isn’t set. Paste it in Settings → CRM; you don’t need the API.
CRM list <name> does not exist	Check the list’s exact name in HubSpot, or use its numeric id. Only company lists work.
a batch needs a CRM list or company ids	Choose a list, or give company ids.

A company is parked with an error

The step failed: it threw, or a call it made was refused, or it ran out of retries. The drawer shows the error and the step’s logs.

The error says	Cause	Fix
step <id> may not call <op>; add it to the step's sources	The step calls an operation motion.yaml doesn’t grant.	Add it to the step’s sources, push, Upgrade, retry.
step <id> may not read <object>; add it to crm.read	Same, for a CRM read.	Add it to crm.read.
step <id> may not propose <action>; add it to crm.propose	Same, for a CRM write.	Add it to crm.propose.
no <provider> key: set PROVIDER_KEYS.<provider> or a tenant key	No key for the provider, and the tenant isn’t in fixture mode.	Set one in Settings → Source keys, then retry.
BULL_API_URL is not set	The Brazilian registry isn’t configured on the platform.	Ask Pruma.
no fixture matches <op> <request>; add one to fixtures/sources	Fixture mode, and no fixture covers this request.	Add a fixture, push, retry.
outcome reason "<reason>" is not in the motion's reasons	The step dropped or held with a reason reasons doesn’t list.	Add the reason, or fix the step.
the step's result for <company> is <n> KiB	The facts or proposals are over 256 KiB.	Keep less in facts: ids and summaries, not whole pages.
anything else, with a stack trace	A bug in the step.	Fix it, push, Upgrade, retry.

Retry re-runs the step for that company: from its drawer, Retry <step>, or for every failed and parked company at once, More actions → Retry failed. Retry only after fixing the cause, or the step fails the same way.

When the fix is in the code or motion.yaml, push it as a new version, Upgrade the batch to it, then retry. Companies that already passed the step keep their results, unless the step’s code changed, in which case they run again.

A company is parked on spend

The drawer says per-company cap of $<n> on <step> reached or per-batch cap…: the next call would have gone over the step’s cap. Or a provider said it’s out of credit.

• Cap: if the spend is expected, raise cap in motion.yaml, push, Upgrade, and retry. If not, look at the step’s calls under Sources before spending more.
• Out of credit: top up the provider account whose key is in use, then retry.

A company is parked on a timer

The step called ctx.wait, and the cell shows when it runs again. Nothing to do; it wakes on its own. If it keeps waiting, the step’s condition never comes true: read its logs.

Companies are waiting on questions

The Questions tab shows them by queue. If nobody’s answering:

• Check the queue’s owner is a member with that handle, in Settings → Members. A queue owned by a handle nobody has can still be answered by the approvers.
• Give queues a deadline and default so the batch never waits forever.

A checkpoint won’t release

Overview shows what it’s waiting for:

Waiting for	Means
companies upstream	some companies are still running, or waiting on questions, before it
cutoff	its at time hasn’t come
event <name>	nobody has sent that event yet
manual release	it has manual: true

An approver can release it any time from More actions.

A changeset won’t seal

It seals when no company is still on its way to it. Companies waiting on questions upstream hold it; parked ones don’t. Answer the questions, or let their deadlines pass.

A changeset has failed or skipped receipts

• skipped, “the CRM connection is read-only”: the tenant’s CRM connection is read-only, as HubSpot is for now. Nothing was written.
• skipped, “already exists” or “already up to date”: nothing needed writing.
• failed: the CRM refused the write; the receipt has its error. Fix the record or the field map, then propose again in a new batch.

Refusals with your name in them

Message	Means
<you> is not the owner of queue <queue> (<owner>) or an approver	Only that queue’s owner or the motion’s approvers can answer.
<you> is not an approver of <motion>	Approving, releasing, upgrading and accepting suggestions need your handle in approvers.
Your role can't …	Your role in the tenant doesn’t allow it. Ask an admin.

Upgrades can be refused

An upgrade is refused if it would remove a step that has started, change its kind or what it runs after, or move it earlier. Make the change in a way that keeps started steps where they are, or open a new batch.