Join our community of builders on Discord!

Stuck Jobs

Normally, deregister reverting with ActiveJobsExist just means your completed jobs are still in their dispute window or not yet released: wait out the window, run release, and the count drops. That flow is covered in Drain & Graceful Exit. This page is for the case where waiting doesn't work. If your active job count has been frozen at the same number for days, you have jobs stuck in an earlier state that releaseJob cannot touch, and your stake stays locked until they are settled.
[!NOTE] There are two ways to clear a stuck job. settleStuckJob(jobId) is the no-fault exit: once the job's deadline plus the resolution timeout (48 hours today) has passed, anyone can call it. Your stake is not slashed and no offence is recorded; the job's fee goes back to the consumer, and a timeout is still recorded against your reputation score. claimTimeout(jobId) works as soon as the deadline passes, but applies the timeout penalty to your stake and records an offence. Read What it costs before using it.

Why the release scheduler doesn't clear them

A job moves Submitted → Acknowledged → Completed, and only a Completed job can be settled with releaseJob. That's all the release scheduler does. If your worker went offline (or crashed, or lost its keys) part-way through a job, that job is frozen in Submitted or Acknowledged and will never reach Completed — the deadline to finish it has already passed. The scheduler skips it forever, the registry keeps counting it as active, and deregister keeps reverting. There are two ways to clear a frozen job, and anyone can call either:
  • settleStuckJob (preferred): available once the deadline plus the resolution timeout (getResolutionTimeout(), 48 hours today) has passed. No slash, no offence; the fee is refunded to the consumer's prepaid balance and your active job count drops by one. It does record a timeout in ReputationRegistry (−500 points on a 0–10,000 score), which lowers your sortition eligibility. Protocol keepers also run this settlement in batches, so a stuck job can clear on its own after that window.
  • claimTimeout: available as soon as the deadline passes. It applies the timeout penalty to the worker that held the job and records an offence. Use it only if you can't wait for the no-fault window.

Am I affected?

CodeBASH
  • 0 — nothing is stuck. You can deregister right now, no penalty.
  • Above 0 and dropping over time — normal settlement. Use Drain & Graceful Exit instead.
  • Above 0 and unchanged for days — you're in the right place. Continue below.

What it costs

settleStuckJob never charges a penalty. The costs below apply only to claimTimeout. The claimTimeout penalty is a fixed amount per stuck job, set on AIConfig and calculated from the minimum worker stake. With the default rates (2% and 5%) and the mainnet minimum stake of 50,000 LCAI:
Job stateDefault penalty per job (mainnet)
Submitted — assigned, never started1,000 LCAI
Acknowledged — started, never finished2,500 LCAI
Both rates are currently 0 on both networks, so today claimTimeout costs only gas. Three things that matter when you're deciding:
  • You can never lose more than your stake. Each penalty is capped at whatever you have left, so once your stake reaches zero, further clears cost nothing.
  • The order doesn't matter. Every job's penalty is a fixed amount, so your total is the same regardless of which you clear first.
  • Your earnings are safe. Penalties only ever touch staked funds — never the balance you've earned from completed jobs.
To confirm the current values for your network:
CodeBASH
The penalty is minWorkerStake × bps ÷ 10000.
Both networks currently return 0 for both rates (mainnet since 13 September 2026), so claimTimeout currently costs only gas. Check before you rely on it, as the rates can be restored. Each claimTimeout still adds an offence to your record, as described under Things to know below.

Find your stuck jobs and your total cost

There's no "list my jobs" call on-chain, so this walks every job in the registry and reports only the ones that belong to you. It reads the job count from the chain, so it always covers the full range. It takes a few minutes and only reads — it changes nothing.
CodeBASH
If you plan to use claimTimeout, its cost is the number of jobs in each list times minWorkerStake × bps ÷ 10000 (see What it costs). Compare that against your stake:
CodeBASH

Decide before you clear

If you can wait — use settleStuckJob once each job's deadline plus 48 hours has passed. It costs nothing but gas. If you use claimTimeout and the cost is a small share of your stake — go ahead, the steps below take a few minutes. If claimTimeout would take most or all of your stake — stop and contact the team before running anything. Many of these stuck jobs come from earlier infrastructure problems that were not the operator's fault, and losing your whole stake to exit is rarely the right trade. Reach out first and describe your situation.

Clearing and exiting

1. Withdraw your earnings first

Penalties can't reach your earnings, but bank them now so nothing is left behind.
CodeBASH
Skip the second command if the balance is 0.

2. Clear each stuck job

Use the job IDs from the scan above:
CodeBASH
If a call reverts, that job's no-fault window hasn't opened yet (or it has already been settled). If you can't wait, use claimTimeout instead, which applies the timeout penalty and records an offence:
CodeBASH

3. Confirm your count reached zero

CodeBASH
If it still isn't 0, the remainder are ordinary completed jobs waiting out the dispute window. Those are free to settle — see Drain & Graceful Exit, or clear them directly once their window has passed:
CodeBASH

4. Deregister

CodeBASH
Your remaining stake is returned to your worker address in the same transaction.

Things to know

  • claimTimeout offences can suspend you, and that's fine. Each claimTimeout counts as an offence. Automatic suspension is effectively off on mainnet (suspensionThreshold 1,000,000) but is 3 on testnet. Suspension does not block deregistration — step 4 works regardless. settleStuckJob records no offence.
  • Both calls are permissionless. Anyone can call them, and the effects land on the worker that held the job. You don't have to call it from your worker key, though it's simplest to.
  • Failed calls cost nothing but gas. If claimTimeout reverts with NotTimedOut, that job's deadline hasn't passed yet. If settleStuckJob reverts, the deadline plus resolution timeout hasn't passed yet. Wait and retry; no state changes on a revert.
  • Clearing is one-way. A settled or timed-out job can't be reopened, and a claimTimeout penalty isn't refundable. This is why the cost check comes first.

Preventing it next time

Stuck jobs happen when a worker disappears mid-job. To avoid repeating this:
  • Follow Drain & Graceful Exit when retiring a worker, so nothing is left half-finished.
  • Don't docker rm a worker that still has obligations on-chain.
  • If your worker crashes, bring it back up promptly. A job only freezes once its deadline passes.

Related pages

Previous PageDrain & Graceful ExitNext PageSlashing & Rehabilitation