Error catalog

Find the code from your exception or CLI output below for troubleshooting steps.

ATOMS-E001: Unclassifiable file under the Atoms path

Severity	warning
Phase	build

Message

File {file} under the Atoms path is neither an Atom, Methods, AtomJob, Shared DTO, support class, nor a migration.

Fix

Move non-Atoms code out of the Atoms path, make the class extend the appropriate atoms/core base class, or move an Atom-side helper into the Atom’s support/ directory (e.g. app/Atoms/GameRoom/support/).

ATOMS-E002: Two files declare the same class

Severity	error
Phase	build

Message

{class} is declared twice under the Atoms path: {first} and {second}.

Fix

Rename one declaration or move it to another namespace. Loading both declarations causes a PHP fatal error.

ATOMS-E010: Framework symbol referenced inside Atom code

Severity	error
Phase	build

Message

{symbol} belongs to a web framework and cannot be used inside Atom code — the Atoms runtime has no framework loaded.

Fix

Move the behavior into a Methods class (runs in your app via $this->app()) or use the atoms/core equivalent.

ATOMS-E011: Global framework helper called inside Atom code

Severity	error
Phase	build

Message

The helper {symbol}() does not exist in the Atoms runtime.

Fix

Use $this->config() for configuration, new \DateTimeImmutable() for time, or move the call into a Methods class.

ATOMS-E012: Monolith class referenced inside Atom code

Severity	error
Phase	build

Message

Reference to monolith class {symbol} inside Atom code. Atom code ships to the platform; your application’s classes do not.

Fix

Pass data across the boundary as a Shared DTO (implement Atoms\Serialization\Payload), call it via $this->app(), or move an Atom-side helper into the Atom’s support/ directory.

ATOMS-E013: Package not declared in atoms-composer.json

Severity	error
Phase	build

Message

Atom code references {symbol} from package {package}, which is not listed in atoms-composer.json.

Fix

Add the package to atoms-composer.json if it is on the approved list; otherwise remove the dependency.

ATOMS-E014: Facade used inside Atom code

Severity	error
Phase	build

Message

Facade {symbol} cannot be used inside Atom code — there is no service container in the Atoms runtime.

Fix

Move the behavior into a Methods class and call it via $this->app().

ATOMS-E015: Shared class references a non-core symbol

Severity	error
Phase	build

Message

Shared class {class} references {symbol}. Shared code runs in both worlds and may only use atoms/core and the PHP stdlib.

Fix

Keep Shared classes pure data: promoted scalar/Payload properties, accessors and factories only.

ATOMS-E016: Shared class contains behavior

Severity	warning
Phase	build

Message

Shared class {class} method {method} looks like behavior (I/O or side effects), not data.

Fix

Shared classes are DTOs. Move behavior to the Atom (Atom-side) or a Methods class (App-side).

ATOMS-E017: env() called inside Atom code

Severity	error
Phase	build

Message

Atoms cannot read your application’s .env.

Fix

Use atoms secrets set KEY --env <environment> and read it with $this->config(‘KEY’).

ATOMS-E018: Native PHP serialization at a boundary

Severity	error
Phase	build

Message

serialize()/unserialize() must not appear in Atom, Shared, or boundary code.

Fix

Boundary values cross as JSON through the Atoms serializer; implement Atoms\Serialization\Payload for structured data.

ATOMS-E019: PHP extension not available in the runtime image

Severity	error
Phase	build

Message

Atom code uses extension {extension}, which the Atoms runtime image does not provide.

Fix

Check the supported extension list in the docs, or move the dependent code into a Methods class.

ATOMS-E020: Unsupported type in data passed between an Atom and the application

Severity	error
Phase	static-analysis

Message

{location} uses type {type}, which cannot cross the Atoms boundary.

Fix

Allowed: scalars, null, arrays of allowed types, Payload DTOs, DateTimeImmutable, backed enums.

ATOMS-E021: ORM object crossing the boundary

Severity	error
Phase	static-analysis

Message

{type} is an ORM object (Eloquent model / Doctrine entity) and cannot cross the Atoms boundary.

Fix

Pass a Shared DTO instead, e.g. PlayerSnapshot::fromUser($user) or $user->only([…]).

ATOMS-E022: Unserializable value in a boundary payload

Severity	error
Phase	runtime

Message

A {type} cannot cross the Atoms boundary.

Fix

Closures, resources, and container-bound objects cannot be serialized. Pass plain data or a Payload DTO.

ATOMS-E023: Payload class is not hydratable

Severity	error
Phase	static-analysis

Message

Payload class {class} must declare all state as promoted constructor properties with allowed types.

Fix

Use public readonly promoted constructor properties; remove non-promoted state.

ATOMS-E024: Value does not match the declared boundary type

Severity	error
Phase	runtime

Message

Cannot denormalize {value} into {type} at {location}.

Fix

The wire value and the declared PHP type disagree — check the manifest for version skew (atoms diff).

ATOMS-E030: Unknown Methods method called from an Atom

Severity	error
Phase	build

Message

{atom} calls $this->app()->{method}(), but {methodsClass} has no public method {method}.

Fix

Add the method to the Methods class, or fix the call — method names are checked statically against the manifest.

ATOMS-E031: Methods call-site signature mismatch

Severity	error
Phase	build

Message

{atom} calls {methodsClass}::{method}() with arguments that do not match its signature.

Fix

Update the call site or the Methods signature; both sides are part of the deployed contract.

ATOMS-E032: AtomJob constructor signature mismatch

Severity	error
Phase	build

Message

{atom} dispatches {job} with arguments that do not match its constructor.

Fix

AtomJob constructor parameters are the dispatch contract — keep the promoted properties and the dispatch site in sync. The array keys you pass to $this->dispatch() are those parameter names.

ATOMS-E033: Dispatched class is not an AtomJob

Severity	error
Phase	build

Message

{atom} dispatches {class}, which does not extend Atoms\AtomJob.

Fix

Extend Atoms\AtomJob, or run the code inline in the Atom instead of dispatching it.

ATOMS-E040: Manifest hash mismatch (version skew)

Severity	warning
Phase	runtime

Message

The monolith was built against manifest {local} but the platform is serving {deployed}.

Fix

Deploy order matters: additive Atom changes deploy Atoms-first; contractions deploy monolith-first. Run atoms diff.

ATOMS-E041: Method not in deployed version

Severity	error
Phase	runtime

Message

Method {method} on {type} does not exist in the currently deployed manifest ({version}).

Fix

The monolith is ahead of the Atom deploy. Deploy Atoms first for additive changes (atoms deploy), then the monolith.

ATOMS-E042: Bundle rejected by platform validation

Severity	error
Phase	deploy

Message

The platform build service rejected the bundle: {reason}.

Fix

Run atoms validate locally — it applies the same checks and must reproduce the failure.

ATOMS-E043: atoms/core version outside the runtime’s supported range

Severity	error
Phase	deploy

Message

Bundle was built against atoms/core {built}, but the platform runtime supports {supported}.

Fix

composer update atoms/core to a supported version and rebuild.

ATOMS-E050: Shipped migration was edited

Severity	error
Phase	build

Message

Migration {file} differs from the version recorded in the deployed manifest.

Fix

Migrations are append-only once shipped. Restore the original file and add a new migration instead.

ATOMS-E051: Migration numbering conflict

Severity	error
Phase	build

Message

Migrations for {type} have a duplicate or non-increasing version at {file}.

Fix

Number migrations with strictly increasing NNN_ prefixes (001_, 002_, …).

ATOMS-E052: Migration likely exceeds the activation budget

Severity	warning
Phase	build

Message

Migration {file} looks heavier than the activation-time budget ({budget_ms}ms).

Fix

Migrations run at Atom activation. Keep them tiny, or restructure as lazy per-row upgrades in Atom code.

ATOMS-E053: Migration failed at activation

Severity	error
Phase	runtime

Message

Migration {version} for {type}/{id} failed: {reason}.

Fix

The Atom stays deactivated, and the failed migration is rolled back. Resolve the reported cause before retrying activation; later migrations run only after this one succeeds. Keep shipped migrations unchanged. Use a corrective migration for unwanted schema changes that applied successfully.

ATOMS-E060: Atom type not deployed

Severity	error
Phase	runtime

Message

Atom type {type} is not present in the customer’s current deploy manifest.

Fix

Deploy the Atom (atoms deploy) or check the class basename — types are matched by basename.

ATOMS-E061: Turn deadline exceeded

Severity	error
Phase	runtime

Message

The Atom’s turn exceeded the configured deadline.

Fix

Turns must stay short. Move slow work to an AtomJob via $this->dispatch(), and check for accidental blocking I/O.

ATOMS-E062: Capacity refused / rate limited

Severity	error
Phase	runtime

Message

The platform refused the request: {reason}. Retryable after backoff.

Fix

The SDK retries automatically where safe. If requests keep failing, inspect the reported reason, Worker logs, and the relevant Cloudflare limits.

ATOMS-E063: Remote Atom exception

Severity	error
Phase	runtime

Message

{class} thrown inside {type}/{id}::{method}: {message}

Fix

This is your Atom code throwing. The sanitized remote trace is attached to the exception.

ATOMS-E064: Callback signature verification failed

Severity	error
Phase	runtime

Message

Rejected a callback from the Worker: bad or missing HMAC signature.

Fix

Check that ATOMS_SHARED_SECRET is identical on the app and the Worker. During rotation the verifier also accepts a callback signed under ATOMS_SHARED_SECRET_PREVIOUS; configure the overlap pair on both sides before flipping either.

ATOMS-E065: Callback replay detected

Severity	error
Phase	runtime

Message

Rejected a platform callback: stale timestamp or reused nonce.

Fix

Usually clock skew (>300s) on the app host, or a genuine replay. Sync clocks; investigate repeated nonces.

ATOMS-E066: No Methods class for callback target

Severity	error
Phase	runtime

Message

A callback targeted {atomType}, but no Methods class resolves for it.

Fix

Create {expectedClass} (or mark a class with #[MethodsFor({atomType}::class)]).

ATOMS-E067: WebSocket ticket acquisition failed (retired)

Severity	error
Phase	runtime

Message

Could not acquire a WebSocket connection ticket for {type}/{id}: {reason}.

Fix

Issue tickets locally with Atoms\Client\Tickets\TicketIssuer. Invalid claims report ATOMS-E068; a missing or malformed shared secret reports ATOMS-E105.

ATOMS-E068: WebSocket ticket claims invalid

Severity	error
Phase	runtime

Message

Cannot issue a WebSocket ticket for {type}/{id}: {reason}.

Fix

Claims are a flat map of string keys to string values: at most 16 entries, at most 2048 UTF-8 bytes over keys plus values, and the assembled ticket must stay under 8192 bytes. Values must be valid UTF-8. The keys “ticket” and “channels” are reserved — channel membership is fixed from the upgrade’s query string, and “ticket” is the query key the ticket itself travels in. The atom type must match ^[A-Za-z_][A-Za-z0-9_]*$ and the id must not be empty. The wire format and these limits are pinned in docs/ws-ticket-protocol.md.

ATOMS-E070: atoms.json missing or invalid

Severity	error
Phase	cli

Message

atoms.json at the repository root is missing, invalid, or does not apply cleanly: {reason}.

Fix

Run atoms init to create it if it is missing, or fix the reported problem in the file. A callback_url reference must be a whole value such as “${ATOMS_CALLBACK_URL}” — correct the syntax when the reason says so, and set the named variable to a non-empty value when the reason says it is unset or empty.

ATOMS-E071: atoms-composer.json invalid or package not allowed

Severity	error
Phase	cli

Message

{reason}

Fix

atoms-composer.json may only contain require (from the approved package list) and repositories.

ATOMS-E072: Deploy credentials missing

Severity	error
Phase	cli

Message

wrangler {command} found no Cloudflare credentials to use.

Fix

Either set CLOUDFLARE_API_TOKEN — in this shell, as a CI variable, or in .env.atoms.<environment> beside atoms.json — with Workers Scripts:Edit on the target account, or run wrangler login in the Worker directory so Wrangler holds its own OAuth session — Atoms passes through whichever it finds, and injects nothing when there is no token. A token is never accepted as a command-line option: a credential in argv is visible to every process on the machine. In CI, supply it to the deploy action as cloudflare-api-token; a runner has no login session to fall back on.

ATOMS-E073: Wrangler not found

Severity	error
Phase	cli

Message

Could not find a Wrangler executable for environment {environment}: {reason}.

Fix

Run npm ci in the Worker directory (atoms-worker/ beside atoms.json, unless you pass –worker-dir) so node_modules/.bin/wrangler exists, or set ATOMS_WRANGLER_BIN to an absolute path. Atoms never downloads Wrangler for you.

ATOMS-E074: Wrangler command failed

Severity	error
Phase	cli

Message

wrangler {command} exited with status {status}.

Fix

Read Wrangler’s own output above; it reports Cloudflare API rejections verbatim. Check that the API token has Workers Scripts:Edit on the target account.

ATOMS-E075: Cloudflare account not configured

Severity	error
Phase	cli

Message

wrangler {command} could not choose a Cloudflare account: no account id was configured, and the credentials reach more than one.

Fix

Add “account_id” to that environment in atoms.json (it is not a secret), or set CLOUDFLARE_ACCOUNT_ID. Wrangler’s own output above lists the accounts it can see; the id is also on the Workers & Pages overview in the Cloudflare dashboard. An account id is only required when the credentials reach several accounts — Atoms no longer demands one up front.

ATOMS-E076: Worker directory missing or incomplete

Severity	error
Phase	cli

Message

The Atoms Worker project for environment {environment} is not usable: {reason}.

Fix

The Worker directory is a committed part of your repository, atoms-worker/ beside atoms.json unless you pass –worker-dir. Scaffold it once with the atoms-runtime-cloudflare init atoms-worker command atoms init prints, run npm ci inside it, and commit it.

ATOMS-E077: Secret would not be readable from Atom code

Severity	error
Phase	cli

Message

Refusing to store {key} as the Worker variable {name}: {reason}.

Fix

Pick a different key. $this->config() resolves through the Worker’s ATOMS_CONFIG_ENV_PREFIX allowlist, and a name outside it — or on its deny list — reads back as null with no error.

ATOMS-E078: Bundle path too long for the archive format

Severity	error
Phase	build

Message

{path} is {bytes} bytes and cannot be stored in the bundle archive.

Fix

The bundle is a ustar tar: a path needs a “/” positioned so the tail is at most 100 bytes and the head at most 155. Shorten the class or directory name.

ATOMS-E079: Vendor dependency resolution failed

Severity	error
Phase	build

Message

Could not resolve atoms-composer.json dependencies: {reason}.

Fix

atoms build installs atoms-composer.json’s packages in an isolated directory (composer install –no-scripts –no-plugins) and ships the resulting PHP sources in the bundle. Check that composer is on PATH and the constraints are satisfiable. For reproducible builds, commit the atoms-composer.lock file the first successful resolution writes next to atoms-composer.json.

ATOMS-E080: Callback channel not configured

Severity	error
Phase	runtime

Message

$this->app()/dispatch() requires the Worker’s callback channel, which is not configured.

Fix

Set ATOMS_CALLBACK_URL on the Worker to your monolith’s callback endpoint (the route where Atoms\Client\Callback\CallbackKernel is mounted). Callbacks are signed with a key derived from ATOMS_SHARED_SECRET, which the Worker requires anyway. atoms dev --callback-url sets the URL for local runs.

ATOMS-E081: Callback signing key missing or unusable

Severity	error
Phase	runtime

Message

ATOMS_CALLBACK_URL is set but the Worker has no usable callback signing key.

Fix

ATOMS_CALLBACK_URL is set but the Worker cannot derive a callback signing key, and Atoms never sends an unsigned callback. The key is derived from ATOMS_SHARED_SECRET (HKDF-SHA256, info “atoms/callback/v1”): set ATOMS_SHARED_SECRET (wrangler secret put) to the base64 of 32 random bytes — the same value your app holds — and the app verifies with the same derivation.

ATOMS-E082: app() called inside a database transaction

Severity	error
Phase	runtime

Message

$this->app()->{method}() cannot be called inside $this->db()->transaction(): the transaction holds a synchronous Durable Object callback that cannot wait for an HTTP round trip.

Fix

Read what you need from the monolith before opening the transaction, or close the transaction and re-open it after the call. $this->dispatch() is allowed inside a transaction — it is queued on commit and dropped on rollback.

ATOMS-E083: Callback request to the monolith failed

Severity	error
Phase	runtime

Message

Callback to the monolith for {atom}::{method} failed: {reason}.

Fix

The Atom reached your app but the call did not succeed. Check that the callback route is mounted and reachable from Cloudflare, that the Methods class exists for this Atom type, and that ATOMS_CALLBACK_TIMEOUT_MS is long enough for the endpoint.

ATOMS-E084: Dispatched job cannot be encoded

Severity	error
Phase	runtime

Message

{class} cannot be dispatched: {reason}.

Fix

Pass constructor arguments to $this->dispatch() by parameter name, for example [‘orderId’ => $id]. Use supported serializable values. Declare the AtomJob constructor parameters as promoted public properties so the application can reconstruct the job.

ATOMS-E085: Invalid timer name

Severity	error
Phase	runtime

Message

Timer name {name} is invalid: it must be a non-empty string within the runtime’s byte limit.

Fix

Pick a name for $this->timers()->schedule($name, $at) that is non-empty and within the runtime’s byte limit for timer names.

ATOMS-E086: Timer limit exceeded

Severity	error
Phase	runtime

Message

{type}/{id} already has {count} scheduled timers, at the per-Atom limit.

Fix

Raise the per-Atom cap on scheduled timers (ATOMS_TIMERS_MAX on the Worker), or cancel/coalesce timers you no longer need before scheduling new ones.

ATOMS-E100: Package layering violation

Severity	error
Phase	static-analysis

Message

{symbol} is referenced from {file}, which is not allowed to depend on it.

Fix

Move the code that needs the symbol up into the adapter package that already depends on it (atoms/laravel, atoms/symfony), or express the need as a PSR interface the lower package can accept. The layers are defined in docs/conventions.md §Layering.

ATOMS-E101: Sleep called inside Atom code

Severity	error
Phase	static-analysis

Message

{symbol}() is called in {class}, but the PHP clock does not advance during CPU work inside a deployed Atom turn. The call can block until the platform resets the Atom for exceeding its CPU limit.

Fix

Delete the sleep. To act later, schedule a timer with $this->timers()->schedule($name, $at) and do the work in onTimer(); to hand work to your app, use $this->dispatch(). Nothing in an Atom may wait on wall-clock time.

ATOMS-E102: Elapsed-time wait loop inside Atom code

Severity	error
Phase	static-analysis

Message

The loop in {class} waits for wall-clock time to pass ({symbol}), which never happens within a single Atom turn.

Fix

Rewrite the loop so it terminates on data rather than on elapsed time, or move the wait out of the Atom: $this->timers()->schedule() delivers onTimer() in a later turn, and $this->dispatch() runs the work in your app.

ATOMS-E103: No queue bridge configured for Atoms callbacks

Severity	error
Phase	runtime

Message

An Atom dispatched {job}, but this application has no Atoms\Client\Callback\QueueBridge wired, so the job cannot be queued.

Fix

Bind a QueueBridge. Laravel wires Atoms\Laravel\Queue\LaravelQueueBridge automatically; Symfony wires Atoms\Symfony\Messenger\MessengerQueueBridge once symfony/messenger and a message bus are present; any other host passes its own QueueBridge to CallbackKernel.

ATOMS-E104: AtomJob constructed inside Atom code

Severity	error
Phase	build

Message

{atom} passes a constructed {job} to $this->dispatch(). An AtomJob’s code stays in your app and is never shipped to the platform, so that class does not exist there.

Fix

Pass the class name and its constructor arguments by name instead: $this->dispatch(TheJob::class, [‘param’ => $value, …]). Naming a class does not require it to ship, and your app reconstructs the real job from those arguments.

ATOMS-E105: Shared secret missing or malformed

Severity	error
Phase	runtime

Message

ATOMS_SHARED_SECRET is missing or is not a base64-encoded value that decodes to exactly 32 bytes.

Fix

Generate one value with openssl rand -base64 32 and configure it on the application and Worker (atoms shared-secret:set reads it from stdin). Use atoms token to derive the bearer token for requests. ATOMS_SHARED_SECRET_PREVIOUS uses the same format.

ATOMS-E106: Schema builder not available on the Atom database connection

Severity	error
Phase	runtime

Message

{member} is not available inside an Atom: Atoms migrations own the schema.

Fix

Ship DDL as Atom migrations (app/Atoms//migrations/NNN_*.sql or .php) — they run at activation, tracked in PRAGMA user_version. The atoms/database-illuminate bridge serves queries and models only, never DDL.

ATOMS-E107: Fast build cannot ship declared dependencies

Severity	error
Phase	build

Message

atoms build --fast skips the vendor stage, but atoms-composer.json declares {count} package(s); the bundle would fail at runtime when an Atom first touches one.

Fix

Drop –fast: with an unchanged atoms-composer.lock the vendor stage resolves offline from .atoms/vendor-cache, so a full build costs no network and no composer run. Or remove the requires from atoms-composer.json. For a fast no-bundle check, use atoms validate.

ATOMS-E108: Worker directory does not match the CLI release

Severity	error
Phase	cli

Message

The Worker directory {dir} was scaffolded from {package} {found}, but this CLI is release {expected}; deploying would ship a runtime that does not match your PHP packages. Run: {command}

Fix

Bring the committed Worker directory up to the CLI’s release with the atoms-runtime-cloudflare upgrade command printed in the message (it rewrites runtime-owned files and leaves wrangler.jsonc alone), review the diff, run npm ci inside the directory, and commit. If the Worker directory is the newer side, update the atoms/* Composer packages to its version instead.

ATOMS-E109: Atoms environment file is unreadable or malformed

Severity	error
Phase	cli

Message

{file} could not be used: {reason}.

Fix

.env.atoms.<environment> beside atoms.json is optional, and is read only for the environment you named. Fix the reported line, or delete the file to resolve from the caller’s environment and atoms.json alone. Each line is KEY=value (an export prefix is allowed); values may be bare, ‘single-quoted’ or “double-quoted”; there is no interpolation and no multi-line value.

ATOMS-E110: Worker uploaded, routing not attached

Severity	error
Phase	cli

Message

wrangler {command} uploaded the script, but Cloudflare refused the routing this environment declares; the Worker is now serving the new bundle on its previous routes.

Fix

Wrangler’s output above names which routing failed. A pattern already assigned to another Worker is refused, not taken over (API code 10020) — remove it there, or give this environment its own pattern under atoms.json “environments”.“”.“routes”. An authentication error on /workers/routes means the credential can upload but not route: add Zone → Workers Routes:Edit and Zone → Zone:Read on the pattern’s zone (custom_domains needs neither). Fixing either and re-running the deploy is safe.