> ## Documentation Index > Fetch the complete documentation index at: https://docs.onecortex.io/llms.txt > Use this file to discover all available pages before exploring further. # Errors > Every error Onecortex shows, with its exact text, its cause and the fix: invoke errors, run errors, agent.yml errors, build errors and startup errors. Paste an error message into search and it lands here. Every entry has the exact text, what causes it and what to do. Placeholders in a message are shown as ``. ## Invoke errors The invoke endpoint answers an error that happens before the run starts with an HTTP status and this body: ```json theme={null} { "error": { "code": "not_found", "message": "That agent does not exist.", "requestId": "req_01K..." } } ``` `requestId` is also in the `X-Request-Id` header. Quote it to [support](/resources/support). ### invalid\_request `400`. `Request must include a 'prompt' field.`, or `The request body must be valid JSON.` The body has no `prompt`, or is not JSON. Your agent was not called. Send a JSON body with a `prompt` string. See [the invoke API](/call/invoke). ### validation\_failed `400`. The message names the field, for example `The 'metadata' field can be at most 4 KB.` A field has the wrong type or size. `sessionId` is 1 to 256 characters, `stream` a boolean, `messages` an array of `{ role, content }`, `metadata` an object of at most 4 KB. Do not retry until the request is fixed. ### unauthenticated `401`. `A valid Onecortex API key is required.` The `Authorization: Bearer` header is missing, or its key is unknown, revoked or expired. The message is the same for every case, on purpose. Check `ONECORTEX_API_KEY` is set in the process that makes the call, and that the key is listed and not **Revoked** or **Expired** on **API keys**. See [API keys](/call/api-keys). ### organization\_suspended `403`. `This organization is suspended. Contact Onecortex support.` Email [support@onecortex.io](mailto:support@onecortex.io). ### not\_found `404`. `That agent does not exist.` The agent ID is wrong, the agent belongs to another organization, or your key is scoped to a different agent. All three answer the same way, so a key cannot find out which agents exist. Copy the ID from the agent's page, and check the key's **Scope** on **API keys**. ### agent\_not\_ready `409`. `This agent has not finished its first deployment yet.` The agent was just created and its first build is still running. Retry once the build succeeds. See [Builds](/deploy/builds). ### agent\_not\_deployed `409`. `This agent has no deployed version. Its first deployment did not succeed.` The first build failed, so there is nothing to serve. Open the failed build, fix the cause it names, and deploy again. Retrying the call does not help. ### agent\_deleted `410`. `This agent has been deleted.` Someone in your organization deleted the agent. A deleted agent cannot be restored. See [Delete an agent](/deploy/delete). ### payload\_too\_large `413`. `The request body can be at most 1 MB.` Send less. Large documents are better fetched by your agent from your own storage than posted in the request. ### rate\_limited `429`. `Too many requests. Try again in seconds.` You are over a [rate limit](/production/limits): 60 requests a minute per organization with a burst of 20, 30 a minute per agent, or 10 open streams per organization. Wait for the `Retry-After` header's seconds, then retry. ### agent\_error `502`. `: `, for example `ValueError: the agent was asked to raise`. Your agent's own code raised. The message is your exception's type and message; the traceback is in your agent's [logs](/observe/logs), not in the response. Fix your code. Retry only if the failure depends on something that changes, like a model provider being briefly down. On a JSON call, the response body still has `status: "failed"` and any text sent before the failure in `result`. ### upstream\_error `502`. One of: * `The agent could not be reached. Try again.` * `The agent stopped before finishing its reply.` * `The agent returned a response Onecortex could not read.` * `This version was built by an older version of Onecortex. Redeploy the agent to serve it.` The first two are transient: retry. The third means your agent yielded something shaped like an event that is not one: see [Streaming and events](/build/streaming). The last needs one redeploy, from **Deploy** on the agent's page. ### agent\_unavailable `503`. `This agent is not available right now. Try again.` The runtime did not answer in time, or is being replaced. Retry with backoff. If it persists for minutes, quote the `requestId` to support. This code is also used when the agent is set up in a way Onecortex cannot run, with the message `Onecortex could not run the agent. The logs have the details.` or one of the [startup errors](#startup-errors). Retrying does not help then: read the agent's logs. ### service\_unavailable `503`. `Onecortex is temporarily unavailable. Try again.` Retry with backoff. ### capacity\_exceeded `503`. `Onecortex is at capacity in this region.` Retry later. ### internal\_error `500`. `The request could not be completed. Try again, and quote the request id if it keeps happening.` A fault in Onecortex. Retry, and if it repeats, send the `requestId` to support. ## Run errors Once a stream has started it has sent `200 OK` and cannot change it, so a failure after that arrives as the last event: ```text theme={null} event: error data: {"v":1,"type":"error","code":"agent_error","message":"ValueError: the agent was asked to raise"} ``` The `code` and `message` are the ones above: most often `agent_error`, `upstream_error` or `agent_unavailable`. Handle `event: error`, or a failed run looks like an empty success. On a JSON call the same failure is a `502` or `503` with `status: "failed"` and an `error` object. See [the invoke API](/call/invoke). ## agent.yml errors Shown when you validate in the wizard, and at the build's **Validate** stage. Each message starts with the file name and, where there is one, the line. The same codes are listed on the [`agent.yml` reference](/agent-yml#validation-errors). ### manifest\_missing `No agent.yml found at .` There is no `agent.yml` in the agent folder you chose. Add one; the message includes a minimal file to copy. Check the **Agent folder** too: it is the folder that holds `agent.yml`. ### manifest\_ambiguous `Both agent.yml and agent.yaml exist at .` Keep one and delete the other. ### yaml\_syntax\_error `agent.yml line , column : ` The file is not valid YAML, so none of it was read. Check the indentation and quoting on that line. Tabs are not allowed for indentation in YAML. ### api\_version\_missing ``agent.yml: `apiVersion` is missing.`` Add `apiVersion: v1` as the first line. ### api\_version\_unsupported ``agent.yml line : `apiVersion` is ``, which this platform does not support.`` Use `apiVersion: v1`. ### field\_missing ``agent.yml: `` is required and is missing.`` Add the field. `runtime` and `entrypoint` are required. The message shows the line to add. ### field\_type\_invalid ``agent.yml line : `` is .`` The value has the wrong type, for example a list where a string belongs. The message shows the corrected line. ### enum\_invalid ``agent.yml line : `` is ``, which is not one of the accepted values.`` For example `runtime: python3.13`. The message lists the accepted values and the closest one. ### entrypoint\_format\_invalid ``agent.yml line : `entrypoint` is ``, which is not a valid entrypoint for runtime ``.`` Python entrypoints are `file.py:name`; TypeScript and JavaScript are `file.ts#name`. See [Entrypoints](/build/entrypoints). ### entrypoint\_runtime\_mismatch ``agent.yml line : `runtime` is `` but `entrypoint` points at ``.`` A Python runtime with a `.ts` file, or the reverse. Change the runtime, or the entrypoint. ### entrypoint\_file\_missing ``agent.yml line : `entrypoint` refers to ``, which does not exist in the build context.`` The path is relative to the agent folder. The message lists the files that are there and the closest match. ### entrypoint\_attribute\_missing ``agent.yml line : `` is not defined at module level in .`` The name after `:` must be defined at the top level of the file, not inside a function or an `if __name__ == "__main__":` block. The message lists the names that are there. ### path\_escapes\_context ``agent.yml line : `` is ``, which points outside the build context.`` Paths may not leave the agent folder, for example with `../`. Move the file into the folder. ### system\_package\_not\_allowed ``agent.yml line : `` is not an available system package.`` The message lists the packages you can install. See [Python agents](/build/python). ### credential\_detected ``agent.yml line : `` looks like a credential.`` A value in `agent.yml` looks like an API key or token. The file is in your repository, so everyone with access can read it. Remove the value, add it as a secret on the agent's **Config** tab, and declare its name under `env.required`. See [Configuration and secrets](/build/configuration). ### dependencies\_file\_missing ``agent.yml line : `dependencies` is ``, which does not exist in the build context.`` Point `dependencies` at a file that exists in the agent folder. The message lists what is there. ### dependencies\_not\_found `agent.yml: no dependency manifest was found in the build context.` Onecortex found no lockfile or dependency file. Add one, or set `dependencies`. The message lists what it looked for, in order. See [Dependencies](/build/dependencies). ### reserved\_directory\_present ``agent.yml: the build context already contains a `_onecortex/` directory.`` `_onecortex/` is where Onecortex writes its build files. Rename or remove yours. ### unknown\_field ``Unknown key `` will be ignored.`` A warning, not an error: the build goes on. Check the spelling against the [`agent.yml` reference](/agent-yml). ### env\_required\_not\_configured `` `` is declared in env.required but is not configured for this agent.`` A warning. Add the key on the agent's **Config** tab, then deploy. ### tree\_truncated ``This repository has too many files to list in full, so file paths in `agent.yml` were not checked here. They will be checked when the agent builds.`` A warning. Nothing to do: the build checks every path. ## Build errors A failed build names its stage and its cause on the build's page, and the version that was live keeps serving. Where a message says the output follows, it is your tool's own output, unedited. See [Builds](/deploy/builds). ### This agent is already deploying `This agent is already deploying. Wait for it to finish and deploy again.` One agent builds one thing at a time. Wait for the running build, or cancel it. ### Your organization is already running 3 deployments `Your organization is already running 3 deployments, the most it can run at once. Wait for one to finish and deploy again.` Three builds, rollbacks included, run at once per organization. Wait for one to finish. ### Commit has no files to build `Commit has no files to build.`, or `Commit has nothing in .` The commit, or the agent folder in it, is empty. Check the agent's branch and folder in **Settings**. ### The source is too large to build `The source is too large to build. Onecortex accepts up to , and this repository reached .` The limits are 50,000 files and 500 MB, for the agent folder. Remove large files, or move the agent into a smaller folder. ### The source archive contains an entry Onecortex will not extract `The source archive contains an entry Onecortex will not extract: ().` A link or path in the repository points outside it. Remove it. ### Installing dependencies failed `Installing dependencies failed.` followed by the installer's output. Your package manager refused. Its own output says why: usually a version that does not exist, a conflict, or a private package. Reproduce it locally with the same lockfile. ### does not publish a build for this architecture `'' does not publish a build for this architecture.` then `Onecortex builds run on 64-bit ARM Linux (aarch64); this package does not publish a compatible build.` A dependency has no ARM Linux wheel or binary. Use a version that publishes one, or a pure Python alternative. See [Python agents](/build/python). ### The built image is too large to deploy `The built image is too large to deploy.` then `Onecortex images may be up to 2048 MB.` Remove large files from the agent folder, or trim dependencies. Large model weights belong in your own storage, fetched at run time. ### The build finished but produced no image `The build finished but produced no image. The build log has the detail.` Read the build log, then deploy again. ### The agent did not start `The agent did not start.` then `It never answered a health check, so the process either stopped or never finished starting. Its own output follows, unedited.` Your agent crashed or hung while starting, during the smoke test. The most common cause is code that runs when the module is imported: a server, an `input()` loop, a long setup. Guard it with `if __name__ == "__main__":`. The output under the message is your process's own. See [Troubleshooting](/production/troubleshooting). ### The agent failed to answer an invocation `The agent failed to answer an invocation.` The smoke test's one invocation ended in an error: usually your agent raised. The detail under the message is the error. A reply that says a model call failed because of the placeholder configuration is not an error: the smoke test passes an agent that answers, whatever it answers. ### The agent answered, but its reply could not be read `The agent answered, but its reply could not be read.` Your agent yielded an object with a `type` field that is not a valid event. Yield plain strings, or valid [events](/build/streaming). ### Your agent could not be started `Your agent could not be started. The previous version is still serving, and nothing about your live endpoint changed.` The new version passed its smoke test but did not start in the runtime. Deploy again. If it repeats, send the build ID to support. ### configuration entries and the maximum is 45 `This agent has configuration entries and the maximum is 45. Remove some and deploy again.` Remove configuration entries on the **Config** tab. ### Configuration is missing a stored value `Configuration is missing a stored value for: . Set it again in your agent configuration and redeploy.` Set those keys again on the **Config** tab, then deploy. ### ran out of time `The deployment stopped at because that step ran out of time. Nothing about your live endpoint changed.` Deploy again. If it happens twice at the same stage, that step is too slow: for a build, usually a very large dependency install. ### The build context from the previous step is no longer available `The build context from the previous step is no longer available. Start a new deployment.` Deploy again. ### Onecortex cannot deploy to that location yet `Onecortex cannot deploy to that location yet. Choose a different one, or contact support if you need this one.` Choose **Europe (Frankfurt)**. See [Regions](/deploy/regions). ## Startup errors Your agent's code is loaded once, when its container starts, so these appear in the smoke test's output and in the agent's logs. ### Failed to import `Failed to import ''.` followed by the Python traceback, then ``If this module runs code when imported (a CLI loop, input(), a long setup task), guard it with `if __name__ == "__main__":`.`` Importing your entrypoint's file raised. The traceback says which import failed and why: often a missing dependency, or code that runs at import. ### has no attribute `'' has no attribute ''. Found: ` The name after `:` in `entrypoint` is not in the file. Pick one from the list. For TypeScript the message is `'' has no export ''. Found: `. ### is not a valid entrypoint `'' is not a valid entrypoint.` A Python entrypoint is a file and a name separated by a colon, for example `agent.py:agent`. ### Onecortex could not determine how to invoke the object at your entrypoint `Onecortex could not determine how to invoke the object at your entrypoint (type: ).` The object is not a framework object Onecortex recognises and cannot be called as a function. Point `entrypoint` at a function that takes the prompt and returns or yields the reply. See [Entrypoints](/build/entrypoints).