Errors and messages
Each message is written as Spotlight shows it. A value in angle brackets, as
in <key>, is filled in when the message is shown. Each row links to the
reference page that documents the message and, where there is one, the guide
that fixes its cause. Messages that report success or progress are on the
pages for each command.
Run page and inbox
Notes on a task
| Message | Cause | See |
|---|---|---|
The run finished without saying where the task should go next. | The run made no handover declaration. | Handover |
The run ended without reporting an outcome. | The run reported no outcome. | Handover |
The run asked for station "<key>". This line has no such station. | The handover named a key that is not a station on the line. | Handover |
The run asked for station "<key>". The task already stands there. | The handover named the station the task stands at. | Handover |
The run asked for station "<key>". Nothing runs there to take up the task. | The handover named a station with no harness. | Handover |
The run asked for station "<key>". Work does not pass there from the task's station. | The current station does not pass to the station named. | Handover |
The run said the work is done. The task is not at the end of its line. | The handover said done at a station without ends: true. | Handover |
The run failed: <message> | The run failed. The message is one of the run failure messages. | Run failure messages, Troubleshoot a run |
Spotlight gave up on the run after <n> attempts. The run did not finish. | The runner was lost, or the host stopped the sandbox at its run timeout, on the last attempt. Failure runner-lost or timed-out, as the last attempt ended. | Failure codes, Troubleshoot a run |
A person stopped the run. The task is back with you. | A person stopped the run. | Handover, Steer or stop a run |
A person stopped the run. | A person stopped a run whose task then moved to a held-back station. | Moves |
Heard while a run held the task. If the run does not pass the task on, the task moves to <Station> when the run ends. | A reaction's happening arrived while a run held the task. | Moves |
Moved to <Station> when the run ended. An event arrived while the run worked. | A held-back reaction applied when the run ended without passing the task on, or when a hook was stopped for looping. | Moves |
<What happened> while <Station> was waiting for an answer. Close the task, or reply to carry on. | A happening that moves the task to the completed station arrived while the task's run waited on a person's answer to its question (not an approval); earlier held-back moves were cancelled. | Moves |
<What happened> while <Station> was working. Close the task, or reply to carry on. | A happening that moves the task to the completed station arrived while a run held it and the task awaited no answer to the run's own question; the run was stopped and the task put to a person. | Moves |
Task cannot move from <from> to <to>. <reason> | 422. A person's move other than starting, parking or closing a task. | Moves, Add a task and move it along a line |
The run said: <note> | Follows the hook's reason when a hook on handover.giving refused the handover. | Handover, Refusing an event |
The task has moved to another station. Messages here reach no one. | Shown on a run page in place of the message box once the task has left the run's station. | Steer or stop a run, Run page composer |
Waiting for your approval | An approval item, from a tool that requires approval or a harness permission a profile sets to ask. | Approvals, Answer the inbox |
Spotlight would like to <intent>. | Above an approval item: what the agent said it wants to do. | What the agent wants |
Spotlight would like to use <name>. <because> | Above an approval item whose agent said nothing about what it wants to do, and above every harness permission. | What the agent wants |
Spotlight asked to <intent>. You edited its inputs. | Above an approval granted with changed inputs. With use <name> in place of a missing intent. | Changed inputs |
Request approved, Request approved with changes or Request dismissed | The title of a decided approval item. | Approvals |
Answering an approval
Each is a 409 from answering an approval item, shown in the card.
| Message | Cause | See |
|---|---|---|
Approval request was already approved. | The approval was decided before. With dismissed where it was dismissed. | Approvals |
Edits must fill every asked input with a value of its kind. Inputs asked: <inputs> | Changed inputs that add or leave out an input, give a value of another type, or leave a value blank. | Changed inputs |
The edited request cannot run. Problem: <where> <why> | A changed input does not fit the tool's input schema, as in input.labelIds[0] is not text. | Changed inputs |
A harness permission takes only yes or no. Its request cannot be edited. | Changed inputs on a harness permission. | Changed inputs |
A dismissed request cannot run with changes. | Changed inputs with a dismissal. | Changed inputs |
Edits are accepted only with a decision to run. | Changed inputs with no decision. | Changed inputs |
Only the person whose connection the tool acts with can approve this request. | An approval by someone other than the person whose own tool rule asked; the task goes to that person, who can approve or dismiss it. | Person rules |
Task <taskId> has nothing waiting for approval at that note. | A decision on a conversation that asks for no approval. | Approvals |
Only a person can approve or dismiss a request. | A decision made with a workspace token. | Approvals |
Run failure messages
Each follows The run failed: . Where a run is refused for more than one
reason, the reasons are joined with ; .
| Message | Cause | See |
|---|---|---|
Runner image <image> can't be pulled. Error: <error> | The host could not pull the line's image and holds no copy of it. Unreadable registry credentials fail the pull even when the host holds a copy, unless the image is named by digest or the copy has no registry digest. Code unprepared. | Run failure messages, Pull runner images from a private registry |
Runner image <image> is refused. <reason> | The host does not serve the image. The reasons are those the Runners page shows. Code unprepared. | Run failure messages, Troubleshoot a run |
Runner image <digest> no longer holds the <harness> harness. | The image changed and lost the station's harness. Code unprepared. | Harnesses, Troubleshoot a run |
The sandbox's egress didn't start. Error: <error> | Egress did not start. The error is one of the egress start failures. Code unprepared. | Egress start failures |
The runner couldn't prepare the run. Error: prepare: git clone <path>: <error>: <output> | A repository could not be cloned. Code unprepared. | Run phases, Point a line at your repositories |
The runner couldn't prepare the run. Error: prepare: preparing <path> did not finish within 10m0s | The checkouts took longer than their time limit. Code unprepared. | Run phases, Limits and timeouts |
The runner couldn't prepare the run. Error: clear an earlier run's outcome: <error> | .spotlight/outcome.json from an earlier run could not be removed. Code unprepared. | Run phases |
The runner couldn't prepare the run. Error: fetch attachment <id>: <error> | An attachment could not be written into the workspace. Code unprepared. | Run phases |
The runner couldn't prepare the run. Error: hand over workspace: <error> | /workspace could not be given to the agent user. Code unprepared. | Run phases |
The runner couldn't start the agent. Error: start agent: <error> | The harness did not start. Code exited. | Run phases |
The runner couldn't start the agent. Error: resume the session: <error> | The harness could not reopen the task's earlier conversation. Code exited. | Run phases |
The runner couldn't start the agent. Error: open a session: <error> | The harness could not open a new conversation. Code exited. | Run phases |
harness_profile_unknown: Harness profile <profile> is not in this team. Station: <Station> | The station's profile names no profile of the team. | Run failure messages, Troubleshoot a run |
catalog_item_unknown: <reason> | The station names a catalog item that does not exist. | Run failure messages, Troubleshoot a run |
catalog_item_wrong_kind: <reason> | The station names a catalog tool as a skill, or a skill as a tool. | Run failure messages, Troubleshoot a run |
not_entitled: <reason> | The workspace's plan does not include a catalog item the station gives. | Run failure messages, Troubleshoot a run |
entitlement_lapsed: <reason> | The plan that included a catalog item the station gives has lapsed. | Run failure messages, Troubleshoot a run |
No runner was provisioned after <n> attempts. Last failure: <failure> | No push pool started a runner. The failure is a code and its detail, as in refused: Provision URL answered <status>. | Provision call failures, Provision runners from your own platform |
Hooks did not answer after <n> tries. Last error: <reason> | The run's run.starting hooks went unanswered on every attempt. | Failure codes, spotlight_hook |
Egress start failures
Each follows The sandbox's egress didn't start. Error: .
| Message | Cause | See |
|---|---|---|
the control plane handed no credential for the sandbox's egress | Spotlight handed no egress credential with the work. | Egress start failures |
egress was not ready within 1m30s | Egress did not publish its authority in time. | Egress start failures |
pull the egress image <image>: <error> | The egress image could not be pulled. | Egress start failures |
Run steps
| Message | Cause | See |
|---|---|---|
Started afresh: <error> | The previous run's workspace could not be restored. The run starts with an empty workspace. | Journal steps |
Setup failed for <path>. Error: <error> | A repository's setup command failed. The run continues without it. | Journal steps, Troubleshoot a run |
Skipped: <error> | The workspace could not be archived for the next run. | Journal steps |
Host log and install script
Host
| Message | Cause | See |
|---|---|---|
the container runtime is not answering yet | The container engine did not respond. The host retries. | spotlight host |
could not report to the control plane, still trying | Spotlight did not respond. The host retries. | spotlight host |
destroyed a sandbox left behind | A sandbox from an earlier host process was removed at start. | spotlight host |
the sandbox ran past its time | SPOTLIGHT_RUN_TIMEOUT passed. The sandbox is stopped with a 30-second grace, and the run is reported timed-out. | spotlight host, Troubleshoot a run |
could not start a sandbox; claiming from this image pauses | A sandbox did not start. Claims for that image pause, longer after each failure in a row. | spotlight host |
gave up the work: its way out did not start | Egress did not start. The run fails, or the check is skipped. | spotlight host |
the host is stopping, so the work is left to be claimed again | The host stopped before the sandbox started. | spotlight host |
the control plane will not have this host; it stops claiming and lets its sandboxes finish | Spotlight refused the host. It exits 3. | Exit codes |
Missing, rotated or unknown pool token, or a workload the trust does not admit | Spotlight refused the host's credential, with 401. | Admission, Run hosts without a stored token |
could not pull the runner image, so it runs the copy it has | A pull failed, and the host has a copy of the image. | Pull runner images from a private registry |
another spotlight host already serves from <state>: <error> | Another host holds the state directory. | Validation |
spotlight host: <config path> is not ready to serve: <problems> | spotlight host install found the host configuration invalid. | spotlight host install |
spotlight host: installing a service on <os> is not supported; run `spotlight host` under your own supervisor | spotlight host install on a platform other than Linux or macOS. | spotlight host install |
Host settings
The host checks every setting before it starts and reports all problems
together. The two sandbox environment problems, found in the egress
environment, are prefixed egress: .
| Message | Cause | See |
|---|---|---|
SPOTLIGHT_URL is required | No address. The runner gives the same message. | Validation |
SPOTLIGHT_TOKEN and SPOTLIGHT_TRUST are different ways in; give one | A token together with a trust or a token file. | Validation |
SPOTLIGHT_TOKEN (a pull pool's token) is required, or SPOTLIGHT_TRUST and SPOTLIGHT_OIDC_TOKEN_FILE to claim through a runner trust | Neither a token nor a trust. | Validation, Install a host |
SPOTLIGHT_OIDC_TOKEN_FILE names the workload token file, and is required with SPOTLIGHT_TRUST | A trust without a token file. | Validation, Run hosts without a stored token |
SPOTLIGHT_CAPACITY: "<x>" is not a count of at least 1 | A capacity that is not a count of at least 1. | Validation |
SPOTLIGHT_RUN_TIMEOUT: "<x>" is not a duration such as 6h | A timeout that is not a duration. | Validation |
SPOTLIGHT_RUNNER_IMAGE: "<x>" is not an image reference such as ghcr.io/acme/runner:main | An image entry that is not an image reference. | Validation, Run a line in your own runner image |
SPOTLIGHT_EGRESS_ALLOW: "*" allows everything; leave the list empty for that | SPOTLIGHT_EGRESS_ALLOW=*. | Validation, Limit where sandboxes can connect |
the sandbox environment sets <NAME>, which only the host holds | A sandbox variable names a host credential. | Validation |
the sandbox environment carries the pool token in <NAME> | A sandbox variable holds the pool token. | Validation |
Runner
| Message | Cause | See |
|---|---|---|
SPOTLIGHT_TOKEN and SPOTLIGHT_HANDED are different ways to be given work; give one | Both are set. | spotlight runner |
SPOTLIGHT_HANDED names the work a host handed this runner, or SPOTLIGHT_TOKEN is the one-run credential a push pool provisioned it with | Neither is set. | spotlight runner |
the work it was handed carries no one-run credential | The handed file holds no credential. | spotlight runner |
could not trust the egress authority, so TLS through egress may fail | A warning. The egress authority could not be added to the image's bundles. | spotlight runner |
nothing was reserved for it in time | With SPOTLIGHT_TOKEN, no work arrived within 5 minutes. The runner exits 0. | spotlight runner |
usage: spotlight runner [harnesses <json>] | An argument other than harnesses. | spotlight runner |
Change stacks are not set up on this deployment. | A station with diffs: true on a deployment without drafting set up. The runner logs the refusal, and the checkout gets no change stack. | Change stacks and decisions |
Egress log
Egress logs these. A harness key or run secret it gives a reason for is not added, and requests go without it.
| Message | Cause | See |
|---|---|---|
the host's allow-list does not admit <host> | The host's egress allow-list does not admit the host the key or secret would be sent to. | What egress adds to requests, Limit where sandboxes can connect |
it is empty or more than one line | A harness key is empty or more than one line. | Harness keys |
the host holds a key of its own for <host> | A run secret is bound to a host a harness key already goes to. | Run secrets |
the host does not let egress read <secret id> | SPOTLIGHT_EGRESS_READS does not admit the AWS Secrets Manager secret. | Run secrets, Give an MCP server a secret |
another secret is already worn in <slot> toward <host> | Another secret already goes in that header or query parameter to the host. <slot> is the header's name, or ?<parameter>. | Run secrets |
it is worn in neither a header nor a query parameter | A run secret's binding names neither a header nor a query parameter. | Run secrets |
it names no header to be worn in | A run secret is bound to a header without a name. | Run secrets |
it names no query to be worn in | A run secret is bound to a query parameter without a name. | Run secrets |
it holds more than one line, so it cannot be worn in a request | A run secret's value is more than one line. | Run secrets |
find the host's AWS identity: <error> | No AWS identity. | Run secrets |
AWS Secrets Manager answered <code> | An AWS error. | Run secrets |
AWS Secrets Manager could not be asked: <error> | AWS was not reached. | Run secrets |
AWS Secrets Manager holds no text for it | The secret has no text value. | Run secrets |
its value in AWS Secrets Manager is not JSON, so it has no <field> field | field is set, and the value is not JSON. | Run secrets |
its value in AWS Secrets Manager holds no text at <field> | The value has no text at field. | Run secrets |
the control plane gave egress nothing to wear | Spotlight refused to redeem the run's secrets. Egress starts with none to add. | Egress start failures |
gave up redeeming the run's secrets; the sandbox goes out wearing none | Egress could not reach Spotlight within 1 minute. | Egress start failures |
Install script
Every message goes to standard error, prefixed spotlight host: .
| Message | Cause | See |
|---|---|---|
need curl or wget to download spotlight | Neither is on PATH. | Install script |
need sha256sum or shasum to check what it downloads | Neither is on PATH. | Install script |
unsupported operating system: <os> | Not Linux or macOS. | Install script |
unsupported architecture: <arch> | Not x86-64 or ARM64. | Install script |
set SPOTLIGHT_TOKEN to a pull pool's token, or SPOTLIGHT_TRUST and SPOTLIGHT_OIDC_TOKEN_FILE to claim through a runner trust | No token and no trust. | Install script, Install a host |
no container runtime answered: install and start Docker or Podman (on macOS, Docker Desktop, OrbStack or Colima), then run this again | No container runtime answered info. | Install script, Install a host |
could not download spotlight from <url> | The binary download failed. | Install script |
could not download the checksum from <url>.sha256 | The checksum download failed. | Install script |
spotlight failed its checksum: expected <sha256>, got <sha256> | The download does not match its checksum. | Install script |
could not pull <image> | The image pull failed. | Install script |
Inside a sandbox
Agent commands
Each command exits 1 and prints its message on standard error.
| Message | Cause | See |
|---|---|---|
no run to hand over: spotlight runs inside a Spotlight workspace | spotlight handover without the run's handover variables. | Environment |
no run to answer for: spotlight runs inside a Spotlight workspace | spotlight reply without the run's handover variables. | Environment |
no run to read a trace from: spotlight runs inside a Spotlight workspace | spotlight trace without the run's handover variables. | Environment |
no run to read history from: spotlight runs inside a Spotlight workspace | spotlight history without the run's handover variables. | Environment |
no run to reach for tools in: spotlight runs inside a Spotlight workspace | spotlight tools, tools search or tools describe without the run's handover variables. | Environment |
not this run's token | The token does not match. | Common behaviour |
reach Spotlight: <error> | Spotlight is unreachable. | Common behaviour |
--next is required | spotlight handover without --next. | spotlight handover |
"<next>" is not one of: <options> | --next names nothing on offer. | spotlight handover |
unreadable handover | The request body was not JSON. | spotlight handover |
read the note: <error> | Standard input could not be read. | spotlight handover |
--to is required | spotlight reply without --to. | spotlight reply |
--body is required | No body, and nothing on standard input. | spotlight reply |
say which remark | The handle is blank. | spotlight reply |
say something back | The body is blank. | spotlight reply |
unreadable answer | The request body was not JSON. | spotlight reply |
read the answer: <error> | Standard input could not be read. | spotlight reply |
--task is required | spotlight trace without --task. | spotlight trace |
say which task | The task id is blank. | spotlight trace |
open <path>: <error> | --out could not be created. | spotlight trace |
--station is required | spotlight history without --station. | spotlight history |
"<key>" is not a station key | --station holds / or \, or is . or ... | spotlight history |
--last counts runs, so it cannot be <n> | --last is negative. | spotlight history |
no line in this team has a station "<key>" | No line of the run's team has the station. | spotlight history |
line "<line>" has no station "<key>" in this team | The named line has no such station, or is not the team's. | spotlight history |
Several lines have a station by that key; name one with --line: <lines> | More than one of the team's lines has the station. | spotlight history |
This run was given no tools. | spotlight tools in a run given no tools. | spotlight tools |
say what the tool does | spotlight tools search without words. | spotlight tools search |
--limit is how many tools to show, at least 1 | --limit is below 1. | spotlight tools search |
say which tool | spotlight tools describe without a tool. | spotlight tools describe |
this run was given no tool "<name>"; the nearest are <tools> | spotlight tools describe names a tool the run was not given. | spotlight tools describe |
no such command "<name>" | No granted tool has that name. | Agent commands |
--<input> is required | A required input without a default was not given. | Agent commands |
<command>: <flag error> | A flag the tool does not take, or a missing value. | Agent commands |
this run was not given "<name>"; it was given: <tools> | The tool is not granted to the run. | Agent commands |
unreadable input: hand the tool JSON | The input is over 8 MiB, or is not JSON. | Agent commands |
--json takes one JSON object, as --json '{"name": "value"}' | The --json value is not a JSON object. | spotlight <tool> |
--<input> cannot be read from stdin when --json is | A piped input named - while --json - read standard input. | spotlight <tool> |
<tool> takes <input>, and <where> <why> | A tool input does not fit its schema. | Input schemas |
<command>: "<value>" follows --<input>, which takes no value; write --<input>=<value> | A value after a boolean flag, as in --notify false. | spotlight <tool> |
<command>: "<argument>" is not a flag | A word outside any flag. | spotlight <tool> |
it is larger than the 4 MB Spotlight reads from a tool | A generated tool's answer is over 4 MB. | Generated tools |
could not read this run's tools to find "<name>": <error> | The tool list could not be read. | Agent commands |
a replay may not answer a remark: it has no effect outside Spotlight | spotlight reply in a replay run. | Replay runs |
a replay may not remember: it has no effect outside Spotlight | spotlight remember in a replay run. | Replay runs |
A replay may not read a task's trace: it leaves nothing behind but its own result | spotlight trace in a replay run. | Replay runs |
this run may only fetch | 403. A git push from a replay run. | Replay runs |
a search may not answer a remark: it studies the station's history and proposes station configs, nothing more | spotlight reply in a search's agent run. recall what the team remembers and propose a memory in place of answer a remark for spotlight recall and spotlight remember. | The search's agent run |
this run cannot propose a candidate: only a search's runs do | spotlight candidate in a run that is not a search's. | spotlight candidate |
This search iteration has proposed its <n> candidates, or tried to too often; end the run | spotlight candidate once the iteration may propose no more. | spotlight candidate |
The search no longer holds this run | spotlight candidate or spotlight cause after the search stopped or moved on. | spotlight candidate |
This search iteration looks into why the search stalled, so it proposes no candidates; record a cause for each failing task with spotlight cause | spotlight candidate in a reflection's run. | spotlight candidate |
this run cannot record a cause: only a search's runs do | spotlight cause in a run that is not a search's. | spotlight cause |
This search iteration proposes candidates; only an iteration that looks into why the search stalled records causes | spotlight cause in a run whose iteration proposes candidates. | spotlight cause |
No failing task <task> among the tasks this reflection looks into; record causes only for the tasks its briefing lists | spotlight cause for a task the briefing does not list. | spotlight cause |
Tool calls and integration requests
| Message | Cause | See |
|---|---|---|
<tool> was dismissed, so nothing was sent. | A person dismissed this call at this station. Their reason follows. | Approvals |
<tool> needs a person's approval before it runs, and they have been asked in their inbox. Nothing was sent. Stop here and end your turn: their answer comes back to you in this conversation. | 409. The tool requires approval, and no unspent grant covers the call. | Approvals, Require approval before a tool runs |
<tool> was not used, so nothing was sent: <person> blocks it on calls made with their connection. | 403. The person whose connection the tool acts with set the tool to "Block". the person it acts as takes the place of <person> when the person has no name. | Person rules |
the integration answered <status>: <body> | The tool's request failed. The body is cut at 500 characters. | Tools |
<tool> acts as the person who started this task, and they haven't connected <integration>. They've been asked in their inbox. Nothing was sent. Stop here and end your turn: you're resumed once they connect. | 409. The tool's integration acts as the person who started the task, and they have not connected it, or the host refused to renew their connection. | Holder, Connect an integration that signs in with OAuth |
<tool> was not used, so nothing was sent: nobody started this task, so there is nobody whose <integration> connection it could act with | The tool's integration acts as the person who started the task, and no person did. | Holder |
<tool> was not used, so nothing was sent: the person who started this task is no longer on the team, so it cannot act with their <integration> connection | The tool's integration acts as the person who started the task, and they have left the team. | Holder |
<tool> was not used, so nothing was sent: this task is already waiting on someone, so nobody can be asked to connect <integration> until they answer | The tool's integration acts as the person who started the task, they have not connected, and the task already waits on a person for something else. | Holder |
using <tool>: the MCP server asked a question in the middle of the call. Spotlight refused the call. It does not pass such questions on to a person | 502. The tool's MCP server asked a question during the call (MCP elicitation), which Spotlight refuses. | Calling a tool |
using <tool>: the MCP server answered with an error: <text> | 502. The tool's MCP server returned a result marked isError. The text is cut at 500 characters. | Calling a tool |
using <tool>: <host> answered <status> | 502. The tool's MCP server answered with an HTTP error, as 401 when the connection could not be renewed. | Calling a tool |
<tool> was held back by a hook, so nothing was sent. | A hook on tool.using refused the call. The hook's refusal follows. | spotlight_hook |
A hook held back the pull request. No pull request was opened. | A hook on pull-request.opening refused the pull request. The hook's refusal follows. | Check or block a pull request before it opens |
Hook <key> refused. Reason: <reason> | A hook on a before event refused the event. | Refusing an event |
Hook <key> failed at step <step> and blocks on failure. Reason: <reason> | A step of a hook on a before event failed, and its failure is block. | Refusing an event |
Hook <key> is broken and blocks on failure. Reason: <reason> | A hook on a before event no longer reads as it was written, and its failure is block. | Refusing an event |
Outbound call to <host> refused. Host is not on the allowed list. | An integration request, hook request or OAuth token exchange to a host not on the deployment's outbound allow-list. | Requests |
Outbound call to <url> refused. URL is not valid. | An outbound call to an address that is not a URL. | Requests |
Outbound call to <host> refused. redirected more than 5 times | An outbound call was redirected more than 5 times. | Requests |
Outbound call to <host> refused. is where an https request was redirected to over plain http, which Spotlight does not follow | An https call was redirected to http. | Requests |
Secret <NAME> not found. Please define it first. | A secret is named but not defined. It fails where it is used. | Where a secret is named |
Secret <NAME> could not be read. This deployment does not read from AWS Secrets Manager. | An integration request made by Spotlight uses a secret from AWS Secrets Manager, and the deployment does not read from it. | Sources |
Secret <NAME> could not be read. AWS Secrets Manager returned <error>. | AWS Secrets Manager refused the read, as with ResourceNotFoundException. an error takes the place of <error> when AWS names none. | Sources |
Secret <NAME> could not be read. AWS Secrets Manager holds no text for it. | The secret has no text value. | Sources |
Secret <NAME> could not be read. Its AWS Secrets Manager value is not JSON. Field expected: <field> | The secret names a field, and its value is not JSON. | Sources |
Secret <NAME> could not be read. Its AWS Secrets Manager value has no text at <field>. | The value has no text at the secret's field. | Sources |
Secret <NAME> holds more than one line. It cannot be sent in a request. | The secret's value is more than one line. | Bindings |
Secrets <A> and <B> are both worn in <slot> toward the same host. A request can carry only one of them. | 409. One call sends two secrets bound to the same header or query parameter of one host. <slot> is the header's name, or ?<parameter>. | Bindings |
Egress responses
| Message | Cause | See |
|---|---|---|
Egress answers only the sandbox it was started for. | 407. No proxy credential, or the wrong one. | Responses |
Egress is a proxy. Please ask it for an absolute URL, or CONNECT to a host. | 400. A request that is neither CONNECT nor an absolute URL. | Responses |
Egress doesn't let this sandbox reach <host>. | 403. The allow-list does not admit the host. | Responses, Limit where sandboxes can connect |
Egress couldn't reach <host:port>. Error: Egress never opens a connection to <ip>. | 502. A tunnelled CONNECT to an always-refused address. | Refused addresses |
Egress couldn't reach <host:port>. Error: Egress opens a connection to private address <ip> only if the allow-list names the host. | 502. A tunnelled CONNECT to a private address the allow-list does not name. | Refused addresses, Limit where sandboxes can connect |
Egress couldn't reach <host:port>. Error: <reason> | 502. Any other failure of a tunnelled CONNECT. | Responses |
Egress couldn't reach <host:port>. | 502. A plain-HTTP or intercepted request that could not be passed on, for any reason. The reason and the URL are left out. | Responses |
Egress couldn't stand in for <host>. Error: <reason> | 502. No certificate could be made for an intercepted host. | Responses |
Resource API and Terraform
Problem types
An error body's type is urn:spotlight:problem:<slug>, with one of these
slugs.
| Message | Cause | See |
|---|---|---|
bad-request | 400. The request is malformed. | Errors |
idempotency-key-required | 400. A create has no Idempotency-Key. | Errors |
malformed-if-match | 400. If-Match is not one entity tag. | Errors |
unsupported-api-version | 400. Spotlight-Api-Version names a version this server does not serve. | Errors |
unauthenticated | 401. No valid credentials. | Errors |
forbidden | 403. The caller's role or token scopes do not allow the request. | Errors, Roles and permissions |
not-found | 404. No such resource that the caller may see. | Errors |
already-exists | 409. A create names an address already taken. | Errors |
moved-on | 409. If-Match names a version that is no longer current. | Errors |
in-use | 409. The write or delete would remove something another resource or a task still uses. | Errors |
conflict | 409. Another conflict with the resource's state. | Errors |
invalid | 422. One or more fields are wrong. | Errors |
idempotency-key-reused | 422. The Idempotency-Key was used for a different request body. | Errors |
precondition-required | 428. An update or delete has no If-Match. | Errors |
refused-upstream | 502. An upstream service refused. | Errors |
Permission titles
| Message | Cause | See |
|---|---|---|
Not allowed to change the <kind> | 403. The caller lacks configure, manage-secrets, manage-runners or manage-token-trusts. | Permissions |
Not allowed to administer the <kind> | 403. The caller lacks administer. | Permissions |
Not allowed to open a workspace | 403. The caller lacks open-workspaces. | Permissions |
Not allowed to plan | 403. The caller lacks plan. | Permissions |
Refusals and warnings
| Message | Cause | See |
|---|---|---|
Workspace <slug> is not empty. Still holds: <what> | 409 in-use. A delete of a workspace that still holds resources. | spotlight_workspace |
Workspace <slug> still has recent changes settling. Please try again shortly. | 409 in-use. A delete of a workspace that holds no resources, while the database still holds rows that refer to it. | spotlight_workspace |
Team <key> is not empty. Still holds: <what> | 409 in-use. A delete of a team that still holds resources. | spotlight_team |
Secret <NAME> is in use. Used by: <names> | 409. A delete of a secret an integration or a harness profile still names. | Rules |
cannot be set on a secret read from AWS Secrets Manager | valueWo on a secret from AWS Secrets Manager. | Sources |
belongs to another pool. Please give each pool its own | A pool token another pool holds. | Pool token, Create a pull pool and get its token |
was used before. Pool tokens work once only | A pool token rotated away, or held by a pool since deleted or replaced. | Pool token |
is not https. Its calls carry a one-run token. A production deployment refuses to make them | A warning on a push pool's provision.url. | Warnings |
names <key>. Runner pool <key> doesn't exist in this workspace | A warning on spotlight_workspace_runners pools. | spotlight_workspace_runners |
names <key>. Runner trust <key> doesn't exist in this workspace | A warning on spotlight_workspace_runners trusts. | spotlight_workspace_runners |
must do something: a webhook, a poll, a schedule, an action to run, or an API description or MCP server to offer tools from | An integration definition with nothing to do. | Top level |
offers tools from one source: an openapi, a graphql or an mcp, not two | An integration definition with two of openapi, graphql and mcp. | Top level |
is read from a url, or written out in full as its document, but not both | An openapi with both or neither of url and document. | openapi |
is a tool name in lowercase words joined by dashes, with * for any run of letters, as in *-issue* | A tools.include or tools.exclude pattern with other characters. | Choosing tools |
offers <n> tools from its <description>. A station can choose between at most 1000 tools. Please name the tools to offer in <kind>.tools.include | An API description gives more than 1,000 tools after the filter. | Choosing tools, Generate tools from an API description |
passes over <operation>. Another operation is also called <name> | A warning. Two operations of an API description have the same tool name; the first is kept. | Generated tools |
passes over <operation>. It has no name that a tool can take | A warning. An operation gives no tool name. | Generated tools |
passes over <operation>. It needs its <in> parameter <name>, which a tool cannot send | A warning. A required cookie parameter, accept, content-type or authorization header, or parameter named like $filter. | Generated tools |
passes over <operation>. One of its parameters cannot be read | A warning. A parameter is malformed, or its $ref points nowhere. | Generated tools |
passes over <operation>. It takes <name> twice | A warning. Two parameters share a name. | Generated tools |
passes over <operation>. It takes a parameter called body as well as a body | A warning. A parameter named body beside a JSON body. | Generated tools |
passes over <operation>. It sends a body that is not JSON. A tool cannot send such a body yet | A warning. A required body that is not JSON. | Generated tools |
passes over <operation>. It takes <name>, which a tool cannot take | A warning. A GraphQL argument, or an input of an MCP server's tool, whose name a tool input cannot have. | Generated tools |
passes over <operation>. It takes "<name>", which a tool cannot take | A warning. An input named json, or not letters, digits, _ and -. | Generated tools |
passes over <operation>. It calls <host>. The connection is worn only toward the host of the description or the host that baseUrl names | A warning. With auth.oauth2 and no baseUrl, the operation's server is on another host than the description. | Generated tools |
passes over <operation>. It needs approval and takes intent, an input that Spotlight keeps for the agent to say what it wants to do. To offer it, switch its approval off in <kind>.tools.approval | A warning. A tool that asks first has an input named intent. | Generated tools, Require approval before a tool runs |
names <key>, but no operation of its <description> has that name | A warning. A tools.approval key names no generated tool. | Choosing tools |
could not be read: <host>: <code> | A warning. The host an API description is read from could not be reached, as in ECONNREFUSED. | Reading the description |
takes a type, or a JSON Schema as its schema, but not both | A tool input with both type and schema. | Tools |
tool <integration>.<tool> cannot take reserved input json. That input hands a tool every input at once | A tool with an input named json. | Tools |
verifies a delivery by hmac, token, asymmetric or jwt | A webhook's verify uses another way. | Verify |
needs a branch or a mark. Without one, no task can be found from it | A raise with no branch and no mark with find: true. | Raise |
authenticates a request by its oauth2 connection, or by the secrets it wears toward the hosts they are bound to | A request's auth uses another way. | Requests |
Integration <integration> takes each person's connection. A person can connect only over oauth2. | connection.holder is requester and there is no connection.oauth2. | Connection |
reads a secret's value. No expression may read a secret. Please name the secret in auth.secrets, and Spotlight wears it toward the hosts it is bound to | An expression contains secret. or secret[. | Secrets in expressions, Give stations a tool from an HTTP API |
must be an expression, written as ${{ ... }} | A field that holds one expression has something around it. | Syntax |
does not check: <message> | A warning. An integration expression parses but does not type-check. . Did you mean <suggestion>? follows when there is one. | Type-checking |
needs HOOK_SIGNING_KEY set to sign OIDC tokens | A hook with oidc where the deployment has no key to sign hook tokens with. | OIDC |
must include read, plan or configure. Secrets, runners and trusts need one of them | A workspace token with none of read, plan or configure. | Scopes, Issue a workspace token |
must name each scope once | A workspace token names a scope twice. | Scopes |
must name an owner before any *, as in repo:acme/* or repo:acme/platform:* | A workspace token trust's subject pattern has no owner before *. | Patterns |
Spotlight refused the exchange. Possible causes: an unknown trust, a token its issuer did not sign for the trust's audience, a workload the trust does not admit, or a closed workspace | 401. An exchange through a workspace token trust was refused. | Exchange, Run Terraform from GitHub Actions without a stored token |
Both a token and an OIDC trust | The provider is configured with a token and a trust. | Provider configuration |
A candidate named <address> already exists. Please choose another name. | 409 already-exists. A replay candidate's name is taken at its station. | Replay candidates |
keeps the station's key, <key> | A replay candidate's station.key names another station. | Checks |
Candidate <id> is being replayed. Please stop its replays first. | 409 in-use. Withdrawing a candidate a replay is running. | Replay candidates |
Web app
Runners page
A host whose images include one it will not start runs from reads
<n> refused under "Images". Its hover lists each refused image with one of
these reasons.
| Message | Cause | See |
|---|---|---|
The host's SPOTLIGHT_RUNNER_IMAGE doesn't admit this image. | The image is not in the host's SPOTLIGHT_RUNNER_IMAGE. | Troubleshoot a run, Run a line in your own runner image |
Image can't be pulled. Error: <error> | The image could not be pulled. | Troubleshoot a run, Pull runner images from a private registry |
Image can't be inspected. Error: <error> | The image could not be inspected. | Troubleshoot a run, Run a line in your own runner image |
Runner is on release <release>. Minimum version required: <release> | The image's runner release is too old. | Troubleshoot a run |
Runner doesn't report its release number. Minimum version required: <release> | The image's runner reports no release. | Troubleshoot a run |
Replays
A run that cannot be replayed shows one of these on a replay set's page, on
hover over its warning sign, and in the "Add runs" dialog. On a replay's result,
it follows Couldn't be replayed or started: in lower case.
| Message | Cause | See |
|---|---|---|
Run doesn't exist | unknown-run. The run is not in the workspace. | Why a run cannot be replayed |
Run has no task of its own | not-a-task-run. A chat's run, or a replay run. | Why a run cannot be replayed |
Task was deleted | task-gone. | Why a run cannot be replayed |
Run hasn't ended yet | still-running. | Why a run cannot be replayed |
Run recorded no starting point | no-starting-point. The run ended before starting points were recorded, or its runner could not record one. | Starting point |
Task briefing wasn't kept | no-briefing. | Why a run cannot be replayed |
Starting workspace is no longer kept | archive-gone. More than 30 days have passed since the run started, and it was in no replay set. | Workspace archives |
Briefing files are gone | attachments-gone. An attachment the task was briefed with is no longer stored. | Why a run cannot be replayed |
Its answer is gone | answer-gone. A replay with the answer could not hand this run its answer: the change people accepted, or what they said when they sent it back, is no longer there. | Room to improve |
Repository has left the line | repository-gone. | Why a run cannot be replayed |
Run wasn't at this station | not-at-the-station. The line no longer has the station. | Why a run cannot be replayed |
Candidate can't run it | candidate-unfit. The candidate was removed, or no longer fits the line as it is. | Why a run cannot be replayed |
Run couldn't be started | cannot-start. The candidate runs no harness a runner can start. | Why a run cannot be replayed |
Couldn't be checked just now | unchecked. Spotlight could not read the run's facts. | Why a run cannot be replayed |
Never started | forgone. | Why a run cannot be replayed |
Failed to start after several tries | dispatch-failed. Queuing the run failed 10 times. | Why a run cannot be replayed |
A replay's results give their reasons in words such as
Asked a person (replays can't) or
Checks couldn't run: checks ran out of time; see
Results for each.
| Message | Cause | See |
|---|---|---|
Only team members can see its replays | The reader is neither on the team nor an owner or admin of the workspace. | Team outcomes |
"Replay set not found", This team has no replay set at that address. Someone may have deleted it. | A replay set page for a set the team does not have at that station. | Replay set page |
"Replay not found", This team has no replay at that address. Someone may have deleted it. | A replay page for a replay the team does not have at that station. | Replay page |
This team has no such run. | A replay run's page the reader may not read, or no such run. | Replay runs |
Please add runs to the set first. | "Start a replay" on an empty set. | Replay set page |
The station is gone from its line. | "Start a replay" on a set whose station has left its line. | Replay set page |
A replay or search of this set is running. Please delete the set after it ends. | "Delete" on a set with a replay or search under way. | Replay set page |
A search of this set is running. Add or take out runs after the search ends or a person stops it. | "Add runs" or taking a run out of a set a search is using. | Replay set page |
Please enter a ceiling above 0., Maximum ceiling: 1,000, Please enter a three-letter currency code, like USD. | The ceiling entered when starting a replay. | Replay set page |
Please enter a whole number from 1 to 5. | The repeats entered when starting a replay. | Replay set page |
The Replays API and
spotlight replay list their own
messages.
Searches
A refused pull request names its reason in words; see Config pull request reasons.
| Message | Cause | See |
|---|---|---|
Only team members can see its searches | The reader is neither on the team nor an owner or admin of the workspace. | Team outcomes |
A search of this station is underway. | "Start a search" while the station is being searched. | Station page |
Create a replay set first. | "Start a search" at a station with no replay set. | Station page |
No replay set covers 5 different tasks yet. | "Start a search" when no set covers runs of 5 tasks. | Station page |
The set covers <n> tasks. A search holds some tasks out. Minimum different tasks: 5, with 1 task for one | A set too small to search on, in the "Start a search" dialog. | Start a search |
Please enter a whole number from <least> to <most>. | An iteration, candidate, at-once or repeats count out of bounds. | Start a search |
Please enter a ceiling above 0., Maximum ceiling: 1,000, Please enter a three-letter currency code, like USD. | The ceiling entered when starting a search. | Start a search |
The station is gone from its line. | A set whose station has left its line, in the "Start a search" dialog. | Start a search |
"Search not found", No search at this address. It may belong to another station. | A search page for a search the team does not have at that station. | Search page |
After its replay on the searched tasks finishes, you can pick this candidate. | "Pick" on a candidate whose replay has not finished. | Picking a candidate |
You can't pick this candidate. Its replay stopped before it finished., You can't pick this candidate. Its replay reached its ceiling before it finished., You can't pick this candidate. Its replay is gone. | "Pick" on a candidate whose replay was stopped, reached its ceiling, or is gone. | Picking a candidate |
Another replay set already guards config changes of station <stationId>. Only one replay set of a station can guard config changes. | "Guards config changes" on a second set at a station. | Guarding a station's changes |
The Searches API, the
Replay checks API and
spotlight replay check
list their own messages.
Inbox notices
| Message | Cause | See |
|---|---|---|
No longer waiting for you. | A notice or inbox item that is not put to the reader, or has left the inbox. | Notices |
Change review
| Message | Cause | See |
|---|---|---|
Spotlight couldn't draft the change stack. | Every drafting attempt failed. | States |
Drafting was interrupted before it finished. | Drafting stopped without a reason. | States |
Members, invites and GitHub
The endpoints for roles, invites, team members and the GitHub connection
refuse with these. A caller who is not an owner or admin of the workspace gets
404 with no message from the invite and team member endpoints.
| Message | Cause | See |
|---|---|---|
This person is not a member of this workspace. | 403. The person whose role is set is not a member of the workspace. | Changing roles |
Only an owner or an admin can set roles. | 403. The caller is not an owner or admin. | Changing roles |
You can only set roles for people below you. | 403. An admin changing an owner or another admin. | Changing roles |
You cannot change your own role. | 403. An admin changing their own role. | Changing roles |
You cannot give a role above your own. | 403. An admin giving the owner role. | Changing roles |
The workspace needs at least one owner. Please make someone else an owner first. | 409. The last owner given another role. | Changing roles, Invite people and change their roles |
Number of email addresses must be 1 to 50. Received: <count> | 422. An invite request with no address, or more than 50 different ones. | Invites |
Email address is not valid. Received: <address> | 422. An address in an invite request is not an email address. Nothing is sent. | Invites |
Role <role> does not exist. Valid roles: owner, admin, member | 422. An invite request with an unknown role. | Invites |
Nobody can be invited as an owner. Please invite them as an admin, then make them an owner. | 403. An invite request with the owner role. | Invites, Invite people and change their roles |
Team <teamId> is not in this workspace. | 422. An invite request names a team that is not in the workspace. | Invites |
An invite to <email> was just sent for this workspace. Please try again. | 409. Another invite to the same address was being sent at the same moment. | Invites |
Invite <inviteId> changed since you loaded it. Please reload and try again. | 409. The invite changed while it was being sent again or revoked. | Invites |
This invite has already been accepted. | 409. Accepting, resending or revoking an accepted invite. | Invites |
This invite has been revoked. | 409. Accepting or resending a revoked invite. | Invites |
This invite has expired. Please ask for a new one. | 409. Accepting an invite more than 14 days after it was last sent. | Invites, Join a workspace from an invitation |
This invite was sent to <email>. Please sign in as <email> to accept it. | 403. Accepting while signed in with another address. | Invites, Join a workspace from an invitation |
<team> already includes this person. | 409. Adding a member to a team they are on. | Invites |
This person is not a member of this workspace. Please invite them first. | 422. Adding someone to a team who is not in the workspace. | Invite people and change their roles |
Only a workspace owner or admin can connect GitHub. | 403. The person is not an owner or admin. | GitHub connection, Connect GitHub to a workspace |
You are not an admin of this GitHub installation. | 403. The person does not administer the installation. | GitHub connection |
GitHub could not confirm this installation is yours. Please sign in again. | 403. GitHub would not say. | GitHub connection |
GitHub installation <id> is connected to another workspace. Please disconnect it there first. | 409. The installation is connected to another workspace. | GitHub connection |
Members page and accepting an invite
The web app shows these on the Members page, a team's General page and the page an invite link opens. When an invite request is refused, the invite dialog shows the message from the table above beneath its fields.
| Message | Cause | See |
|---|---|---|
Not an email address: <addresses> | Text under "Email addresses" in the invite dialog that is not an email address. Nothing is sent. | Invite people |
Not sent. Please resend it from Pending invites. | The outcome for an address whose invite email could not be sent. | Invites |
Sorry, the invite couldn't be sent again. | "Resend invite" failed. | Follow up on a pending invite |
Sorry, the invite couldn't be revoked. | "Revoke invite" failed. | Follow up on a pending invite |
Sorry, the role couldn't be changed. | "Change role" on the Members page failed. | Changing roles |
Sorry, the member couldn't be added. | "Add a member" on a team's General page failed. | Add a member to a team |
Invitation is for <invited address>, not <signed-in address>. Please sign in as <invited address> to accept. | The invite page opened while signed in with another address. | Join a workspace from an invitation |
Invitation already accepted. | The invite link of an accepted invite. | Join a workspace from an invitation |
Invitation withdrawn. | The invite link of a revoked invite. | Join a workspace from an invitation |
Invitation expired. Please ask for a new one. | The invite link of an expired invite. | Join a workspace from an invitation |
Invitation link doesn't work | A link that matches no invite, or a link of an invite sent again since. | Join a workspace from an invitation |