fix(twenty-server): stop the yarn-install Lambda from running out of memory (#23805)

## Context

Sentry issue
[7438578272](https://twenty-v7.sentry.io/issues/7438578272/) (Logic
Function Layer Build Failed, 7.9K events over 3 months): the
yarn-install tool Lambda dies with `Runtime.OutOfMemory` / `signal:
killed` while building an application's dependency layer. Every layer
build for the affected application fails permanently, each
database-event trigger re-attempts it, and one workspace produced ~2.5K
events in the last week alone.

## Root cause

The offending application declares `twenty-ui@1.0.0-alpha.0` (181MB
unpacked, dragging in 141MB of `@tabler/icons*`) and dev tooling as
production `dependencies` of server-side logic functions. Installing
that tree needs just under 3GB during Yarn 4's fetch/link phase, so the
1024MB sandbox is OOM-killed. And even a successful install could never
ship: AWS caps a function plus all its layers at 250MB unzipped.

The user never sees any of this: the OOM is retried forever, and nothing
tells them their dependencies are the problem.

## Fix

1. **Raise the yarn-install Lambda to 4096MB** so legitimate dependency
trees install. Tool function names now include the
memory/timeout/ephemeral-storage constants in their content hash, so a
config change rotates the function name and the ensure path creates a
fresh function with the new configuration — without this, the constant
change would never reach already-deployed functions (their config is
only applied at creation, and the ensure path early-returns when the
function exists).
2. **Propagate Lambda's own errors to the user.** The install OOM
(`Runtime.OutOfMemory` on the invoke) and the layer size rejection
(`InvalidParameterValueException` at `PublishLayerVersion`) map to a new
`LOGIC_FUNCTION_DEPENDENCIES_SIZE_EXCEEDED` code telling the user to
move packages their logic functions don't import out of `dependencies`.
Surfacing per API boundary:
- **Sync / install (CLI)**: the workspace migration interceptor formats
it into the same metadata validation error shape the SDK already
renders, as one `logicFunction` entry carrying the remedy and the
underlying AWS detail — no SDK rendering changes needed.
- **`executeOneLogicFunction`**: mapped to `UserInputError` in the
GraphQL handler.
- **Route triggers**: HTTP 422 with the user-facing message, no Sentry
capture.
- **Background triggers**: skip instead of retrying, since no retry can
succeed until the user changes their application.

## Test

The error originates in AWS behavior, which CI (local driver, no AWS)
cannot reproduce — so the chain is verified link by link:

- **Real AWS, manual (not in CI)**: reproduced with the offending
application's actual package.json against real Lambdas in the dev
account — OOM-killed at 1024MB and 2048MB (exact prod error signature),
install succeeds at 4096MB (~4min), and the resulting 292MB layer is
rejected by `PublishLayerVersion` with the exact
`InvalidParameterValueException` this PR matches. Same matrix reproduced
in local cgroups beforehand.
- **Server unit specs**: AWS error payload → exception mapping
(`build-yarn-install-failure-exception`), exception → validation payload
formatting (interceptor handler), `executeOneLogicFunction` GraphQL
mapping, route filter 422 mapping, tool-function/layer name hashing.
- **SDK integration spec (mocked server)**: runs the real `app dev`
orchestrator on the minimal app with `syncApplication` mocked to return
the validation-shaped failure, and asserts the CLI report renders the
error code and remedy. It covers CLI rendering only — no test installs
actual oversized dependencies, by design.
- Docs updated (dependency size limits, sync failure taxonomy, route
platform error responses).
This commit is contained in:
Charles Bochet
2026-08-06 15:45:37 +02:00
committed by GitHub
parent c7cfd143c7
commit a7324252fd
22 changed files with 405 additions and 23 deletions
@@ -76,4 +76,4 @@ The scaffolder pins `twenty-sdk` and `twenty-client-sdk` to its own version —
Keeping either package under `dependencies` pulls it into the installed app's runtime bundle, where it is dead weight. `twenty dev:build` emits a warning when either is still listed under `dependencies`.
Add your app's own runtime dependencies (libraries your logic functions actually import at runtime) under `dependencies` as usual.
Add your app's own runtime dependencies (libraries your logic functions actually import at runtime) under `dependencies` as usual. Keep the tree lean: `dependencies` are installed into a runtime layer capped at 250MB unpacked, and a sync or install fails with a dependencies size error beyond that — UI libraries and dev tooling belong in `devDependencies`.
@@ -172,6 +172,10 @@ For security reasons, response headers are restricted to an allow-list. Any head
The status code must be a valid HTTP status code (between 100 and 599). Response header names are matched case-insensitively.
</Note>
#### Platform error responses
Beyond your handler's own responses, the platform answers route calls directly in some situations: `404` when the route or function does not exist, `403` when the application is stopped, `429` when the execution rate limit is hit, and `422` when the application's production `dependencies` are too large to install — see [dependencies size limits](/developers/extend/apps/getting-started/project-structure#dependencies).
#### Server route trigger
`httpRouteTriggerSettings` exposes a function under `/s/` and resolves the workspace from the request host — which works when each workspace has its own domain. Third-party providers, however, deliver every tenant's events to **one** URL. For that case, use `serverRouteTriggerSettings`.
@@ -121,5 +121,6 @@ When something goes wrong, the metadata diff and named errors let you place the
- **Manifest build error** — the CLI fails before syncing (`MANIFEST_BUILD_FAILED`, `TYPECHECK_FAILED`); fix your app source.
- **Sync / migration error** — the build succeeds but applying the diff fails, naming the entity and `universalIdentifier`; fix the conflicting metadata.
- **Dependencies size error** — the sync or install fails because the app's production `dependencies` are too large to install as a runtime layer (`LOGIC_FUNCTION_DEPENDENCIES_SIZE_EXCEEDED`); move packages your logic functions do not import at runtime (UI libraries, dev tooling) to `devDependencies`.
- **App code runtime error** — the sync succeeds but your logic functions or components misbehave at runtime; check [function logs](/developers/extend/apps/operations/cli).
- **Local instance state** — none of the above and the workspace still looks wrong; work down the recovery ladder.