Screeps Error Codes and Return Values

DIAGNOSTIC NETWORK

High-frequency error paths

Start from a return code, then move through the APIs, object hubs, focused guides, tools, and accepted runtime verification already connected to that failure branch.

10 priority paths

return -9

`ERR_NOT_IN_RANGE`

The target exists, but the acting object does not satisfy the method's range rule. Confirm the real return code before deciding to move.

What should I check next?

Confirm that the target exists and is valid for the current method.
Store the action result and enter the range branch only when the real result is -9.
For Creep actions, inspect the current range before deciding whether to call moveTo().
Retry the original action on a later tick and verify position, Store, or target state.

return -2

`ERR_NO_PATH`

Movement or pathfinding could not find a usable path under the current constraints. Do not blindly repeat moveTo(); identify which path constraint failed.

What should I check next?

Confirm that the target position and destination room can be resolved; cross-room work also needs valid vision and exits.
Inspect walls, impassable terrain, Ramparts, and other objects that change walkability.
Check range, routeCallback, roomCallback, or CostMatrix rules that may exclude every usable route.
When using PathFinder directly, inspect incomplete, path, cost, and ops rather than the path array alone.

API surfaces

creep.moveTo(target, opts)Game.map.findRoute(from, to, opts)PathFinder.search(origin, goal, opts?)

Object hubs

Creep Room

Focused guides

ERR_NO_PATH troubleshooting →PathFinder and CostMatrix →

Related tools

Room Snapshot Diagnostic →

return -6

`ERR_NOT_ENOUGH_RESOURCES`

The current method lacks a required resource. -6 does not always mean Energy; return to the specific API and identify the missing stock, Credits, or cost.

What should I check next?

Identify which API returned -6 and which resource that method actually consumes.
Inspect the current Creep, Structure, room, or account stock instead of relying on planned values.
Compare the requested amount with real availability, transaction cost, or recipe consumption.
Retry only after the resource state changes, then store the new result to confirm the failure branch changed.

API surfaces

spawn.spawnCreep(body, name, opts?)terminal.send(resourceType, amount, destination, description?)Game.market.deal(orderId, amount, roomName?)lab.runReaction(inputLab1, inputLab2)lab.boostCreep(creep, bodyPartsCount?)factory.produce(resourceType)

Object hubs

StructureSpawn Game.market

Focused guides

Dynamic Creep body and Energy →Terminal resource sending →Power Spawn resource checks →

return -4

`ERR_BUSY`

The object is busy with an incompatible action. For Spawn workflows, inspect occupancy before deciding to queue, wait, or use another Spawn.

What should I check next?

Confirm that the current API actually documents ERR_BUSY instead of borrowing rules from another method.
For a Spawn, inspect spawn.spawning and whether the queue already assigned work to it.
Confirm that the same tick is not submitting mutually exclusive actions to the same object.
After waiting or reassigning, store the next result so a persistent failure is not mistaken for normal queueing.

API surfaces

spawn.spawnCreep(body, name, opts?)spawn.renewCreep(creep)spawn.recycleCreep(creep)

Object hubs

StructureSpawn

Focused guides

spawnCreep() return codes →renewCreep() and Spawn state →recycleCreep() return-value boundaries →

Related tools

Spawn Queue and Replacement Planner →

return -7

`ERR_INVALID_TARGET`

The target exists, but it does not satisfy the method's target contract. Validate target type and state before checking range or resources.

What should I check next?

Log the target and confirm it is not undefined, null, or a stale cached object.
Confirm that object type, ownership, and current state satisfy this API's target contract.
Separate invalid-target failures from range and capacity failures; do not hide a bad target behind moveTo().
After correcting the target, store the new result and verify the action state on a later tick.

API surfaces

creep.transfer(target, resourceType, amount?)creep.withdraw(target, resourceType, amount?)creep.upgradeController(controller)room.createConstructionSite(x, y, structureType)

Object hubs

Creep Room StructureController

Focused guides

Safe withdraw() usage →Create Construction Sites →

Related tools

Room Snapshot Diagnostic →

return -8

`ERR_FULL`

The target does not have enough remaining capacity. Inspect real free capacity and account for other same-tick actions that may reserve or change it.

What should I check next?

Identify which target rejected the action and read the relevant Store or structure capacity.
Use getFreeCapacity(resourceType) for the specific resource channel instead of relying on total capacity alone.
Check whether other Creeps or Structures are also writing to the same target in the current tick.
Recalculate a safe amount before retrying and store the new return code.

API surfaces

creep.transfer(target, resourceType, amount?)link.transferEnergy(target, amount?)lab.runReaction(inputLab1, inputLab2)

Object hubs

Creep

Focused guides

Link target capacity →Lab reaction output capacity →

return -11

`ERR_TIRED`

The object cannot act again yet: a Creep may have fatigue and a Structure may still be on cooldown. Read state instead of blindly retrying.

What should I check next?

For Creep movement, inspect creep.fatigue and the MOVE-to-body-weight ratio.
For Structure actions, read the relevant cooldown and confirm it reached zero.
Avoid repeatedly submitting the same action and flooding logs while fatigue or cooldown is clearly active.
Retry after the state recovers and store the result to confirm the failure branch is gone.

API surfaces

creep.moveTo(target, opts)link.transferEnergy(target, amount?)

Object hubs

Creep

Focused guides

MOVE, fatigue, and body ratio →Link cooldown →

return -10

`ERR_INVALID_ARGS`

One or more arguments do not satisfy the method contract. Log real values and check type, order, range, and option-object shape one field at a time.

What should I check next?

Identify the exact call shape or overload and compare it with the current API parameter order.
Log the real body, name, roomName, resourceType, amount, or opts values one by one.
Check numeric ranges, string formats, array contents, and option fields for invalid values.
After correcting the inputs, call once and store the result so repeated calls do not hide the original argument failure.

API surfaces

spawn.spawnCreep(body, name, opts?)room.createConstructionSite(x, y, structureType)terminal.send(resourceType, amount, destination, description?)Game.market.createOrder(params)

Object hubs

StructureSpawn Room Game.market

Focused guides

Market createOrder() arguments →Construction Site arguments →

return -3

`ERR_NAME_EXISTS`

The requested Creep name is already in use. Name generation is part of the Spawn lifecycle and should be made unique before queueing or spawning.

What should I check next?

Log the requested name and check whether Game.creeps[name] already exists.
Confirm that the Spawn queue did not preassign the same name to multiple pending tasks.
Use a predictable but unique naming strategy, such as role, sequence, and Game.time.
After generating a new name, run dryRun or the real call again and store the result.

API surfaces

spawn.spawnCreep(body, name, opts?)

Object hubs

StructureSpawn

Focused guides

spawnCreep() return codes →

Related tools

Spawn Queue and Replacement Planner →

return -14

`ERR_RCL_NOT_ENOUGH`

The current room Controller level or structure activation state does not permit the action. Check RCL, structure limits, and isActive() before changing the plan.

What should I check next?

Read room.controller?.level and confirm that the room is controlled by the Controller your code expects.
For construction work, check the current RCL unlock level and structure-count limit.
For existing Structures, check structure.isActive(); existence alone does not guarantee the structure can act.
When RCL is insufficient, change the queue or wait for an upgrade instead of submitting a guaranteed failure every tick.

API surfaces

room.createConstructionSite(x, y, structureType)

Object hubs

Room StructureController StructureSpawn

Focused guides

Controller downgrade and recovery →Controller Safe Mode →

Constant	Value	Practical meaning	Next
`OK`	`0`	The command was accepted. The visible result may still appear on a later tick.	—
`ERR_NOT_OWNER`	`-1`	The object is not controlled by you, or the method requires ownership.	—
`ERR_NO_PATH`	`-2`	No route or path could be found under the current movement options.	Diagnostic path ↑
`ERR_NAME_EXISTS`	`-3`	A requested name is already in use, commonly when spawning a Creep.	Diagnostic path ↑
`ERR_BUSY`	`-4`	The object is already performing an incompatible action, such as a busy Spawn.	Diagnostic path ↑
`ERR_NOT_FOUND`	`-5`	The requested object, resource, reaction, or state was not found.	—
`ERR_NOT_ENOUGH_RESOURCES`	`-6`	The action lacks the specific resource required by the current method.	Diagnostic path ↑
`ERR_NOT_ENOUGH_ENERGY`	`-6`	A legacy Energy-focused name for the same numeric result; check the current method's documented resource requirement.	—
`ERR_INVALID_TARGET`	`-7`	The target exists but cannot be used by this method.	Diagnostic path ↑
`ERR_FULL`	`-8`	The target store, structure, or capacity is already full.	Diagnostic path ↑
`ERR_NOT_IN_RANGE`	`-9`	The acting object is too far from the target. Move closer and retry on a later tick.	Diagnostic path ↑
`ERR_INVALID_ARGS`	`-10`	One or more arguments do not match the method contract.	Diagnostic path ↑
`ERR_TIRED`	`-11`	The object is on cooldown or a Creep has fatigue.	Diagnostic path ↑
`ERR_NO_BODYPART`	`-12`	The Creep lacks an active body part required for the action.	—
`ERR_RCL_NOT_ENOUGH`	`-14`	The room Controller level does not permit the requested structure or action.	Diagnostic path ↑
`ERR_GCL_NOT_ENOUGH`	`-15`	The account does not have enough control level for the requested claim or expansion.	—

DEBUGGING PATTERN

Store the result once

Call the action once, save its result, log the result with context, and branch from that value. Avoid calling the same state-changing method repeatedly inside one expression.

NEXT STEP

Check the full room state

When several systems fail together, use a room snapshot to inspect workforce, Energy, Controller pressure, construction, and CPU.

Open room diagnostics →