<field>.
Invoke errors
The invoke endpoint answers an error that happens before the run starts with an HTTP status and this body:requestId is also in the X-Request-Id header. Quote it to 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.
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.
organization_suspended
403. This organization is suspended. Contact Onecortex support.
Email [email protected].
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.
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.
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 <n> seconds.
You are over a rate limit: 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. <ExceptionType>: <message>, 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, 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.
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. 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 sent200 OK and cannot change it, so a failure after that arrives as the last event:
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.
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 theagent.yml reference.
manifest_missing
No agent.yml found at <path>.
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 <path>.
Keep one and delete the other.
yaml_syntax_error
agent.yml line <n>, column <n>: <parser message>
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 <n>: `apiVersion` is `<value>`, which this platform does not support.
Use apiVersion: v1.
field_missing
agent.yml: `<field>` 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 <n>: `<field>` is <what was found>.
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 <n>: `<field>` is `<value>`, 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 <n>: `entrypoint` is `<value>`, which is not a valid entrypoint for runtime `<runtime>`.
Python entrypoints are file.py:name; TypeScript and JavaScript are file.ts#name. See Entrypoints.
entrypoint_runtime_mismatch
agent.yml line <n>: `runtime` is `<runtime>` but `entrypoint` points at `<file>`.
A Python runtime with a .ts file, or the reverse. Change the runtime, or the entrypoint.
entrypoint_file_missing
agent.yml line <n>: `entrypoint` refers to `<file>`, 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 <n>: `<name>` is not defined at module level in <file>.
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 <n>: `<field>` is `<value>`, 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 <n>: `<package>` is not an available system package.
The message lists the packages you can install. See Python agents.
credential_detected
agent.yml line <n>: `<field>` 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.
dependencies_file_missing
agent.yml line <n>: `dependencies` is `<file>`, 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.
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 `<key>` will be ignored.
A warning, not an error: the build goes on. Check the spelling against the agent.yml reference.
env_required_not_configured
`<KEY>` 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.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 <sha> has no files to build., or Commit <sha> has nothing in <folder>.
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 <n> <files or bytes>, and this repository reached <n>.
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: <path> (<reason>).
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
'<package>' 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.
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.
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.
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 <n> 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: <keys>. 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 <stage> 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.
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 '<file>'. 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
'<file>' has no attribute '<name>'. Found: <names>
The name after : in entrypoint is not in the file. Pick one from the list. For TypeScript the message is '<file>' has no export '<name>'. Found: <names>.
is not a valid entrypoint
'<value>' 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: <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.