Loading

Limits and the Circuit Breaker

Every extension runs within fixed limits, and a circuit breaker switches off one that keeps failing. This article sets out the limits, what trips the breaker, how to tell that it has, and how to bring an extension back once it is fixed.

Where to find it

Architect Panel → Automation:

  • Extensions — open an extension for its Limits, Circuit breaker card and Recent runs

The limits

  • Time: each hook has a time budget, shown on the Hooks card (for example 250 ms to draw a field). The extension's own Timeout (ms), 2,000 ms unless changed, can only shorten that budget, never lengthen it. A run that overruns ends with "the extension ran longer than it is allowed to".
  • Memory: the extension's Memory Limit (MB), 64 MB unless changed. A run that exceeds it ends with "the extension used more memory than it is allowed to".
  • Data: one query returns at most 1,000 records.
  • Nesting: an extension that causes another to run can go at most three levels deep.
  • Code size: the code checker refuses code over 64 KB or that is too complex, so very large extensions must be split.

The detail panel also shows Outbound hosts and an e-mails-per-run figure. Extensions cannot currently make web requests or send e-mail at all, so those values are recorded but have no effect.

The limits are not a sandbox. Code that runs inside the platform shares the request it runs in: a call that blocks cannot always be interrupted, and a fatal error affects the page being drawn before the breaker can act.

What trips the circuit breaker

  • Five failures in a row, or
  • Twenty or more failures within five minutes, when more than half of that window's runs failed, or
  • A single crash of the page the extension was drawing.

When it trips, the extension's status becomes quarantined and it stops running at once. The reason is recorded in plain words ("it failed 5 times in a row", "it crashed the page it was drawing") and the Error Log gets an entry starting "Extension" followed by its number and "was turned off automatically". An extension is also quarantined, with the reason "the code checker has been updated, so this needs checking again", after a platform update changes the code checker.

Bringing an extension back

  1. Open the extension and read the Circuit breaker card (State shows "TRIPPED at" and the time) and the Recent runs table (When, Hook, Outcome, Duration, Peak memory, Message).
  2. Have the cause fixed in App Code, which saves a new version, then approve that version.
  3. Click Put live on the fixed version. Putting a version live clears the breaker.

Clear the breaker on its own resets the counters ("Circuit breaker cleared.") but leaves the status quarantined, so the extension stays off until somebody puts a version live. Nothing re-enables a quarantined extension automatically.

Reading the run history

Recent runs lists the latest 50 records. Every failure is recorded, but only about one successful run in fifty, to keep the table small. So a short list with no successes does not mean the extension is not running; and the warning that live extensions "none has ever run" can appear for an extension that is in fact running correctly.

What goes wrong and how to tell

  • Breaker column says "tripped": quarantined by the breaker. Follow the steps above.
  • Quarantined but Breaker shows "-": switched off after a crash or a checker update. Read the reason on the detail panel.
  • "no runner is configured for this cell" or "the runner could not be reached" in Recent runs: the hook needs the separate extension runner, which this system lacks or cannot reach. These failures count towards the breaker.

Worked example

An extension that formats a contract field starts failing after a field is renamed. After five failures in a row it is quarantined, the form falls back to the standard control for that field, and the Error Log records why. The architect sees "it failed 5 times in a row (last: error)" on the Extensions screen, asks the developer to update the field name, approves the new version and clicks Put live. The breaker clears and the formatted value returns.

Recommendations

  • Check the Extensions screen after any platform update for quarantined items.
  • Fix, then Put live; clearing the breaker alone does nothing visible.
  • Keep extensions small and fast, well inside their hook's budget.
  • Do not commission extensions that call outside services; they cannot today.