The build fails at Validate
agent.yml has a mistake. The message names the line and shows the corrected lines to paste. The wizard’s Validate step runs the same checks, so you can check a change before you push it. See the agent.yml reference.
The build fails at Build image
Installing dependencies failed. Your package manager’s own output follows the message. Run the same install locally from a clean environment with your lockfile: it fails the same way.
'<package>' does not publish a build for this architecture. Onecortex builds for 64 bit ARM Linux. A package with a native extension needs a wheel or binary for aarch64. Upgrade to a version that ships one, or choose a pure Python alternative. See Python agents.
The built image is too large to deploy. The limit is 2048 MB. Look for model weights, datasets or a committed virtual environment in the agent folder, and for a heavy dependency pulled in by accident.
The build fails at Smoke test
The agent did not start. Your process crashed or hung before it answered a health check within 30 seconds. The output under the message is your process’s own, and usually names the cause:
- A traceback from an import. A dependency is missing from your dependency file, or it is imported under a different name.
Failed to import, with a hint aboutif __name__ == "__main__":. The file runs code when it is imported: a server, aninput()loop, a long setup. Guard it. See Entrypoints.has no attributeorhas no export. The name inentrypointis not in the file. The message lists what is.- No output at all. The process is still starting after 30 seconds. Move slow setup, such as building a large index, out of import time, or make it lazy.
The agent failed to answer an invocation. The smoke test’s call ended in an error, usually because your agent raised. The detail under the message is the exception. The call uses placeholder configuration values, so code that crashes when a secret is not a real key fails here: catch the model’s error and answer with it instead.
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.
The agent is not found
Onecortex could not determine how to invoke the object at your entrypoint means Onecortex does not recognise the object and cannot call it. Common cases:
- A LangGraph
StateGraphthat was never compiled. Exportbuilder.compile(). - A class, rather than an instance of it. Export the instance.
- A framework Onecortex does not recognise. Wrap its run call in a function.
A call answers 409
This agent has not finished its first deployment yet. The first build is still running. Call again when it succeeds.
This agent has no deployed version. Its first deployment did not succeed. Open the failed build, fix the cause, and deploy.
After an agent’s first version, a running or failed build never makes calls fail: the live version keeps answering.
A call answers 401 or 404
401, A valid Onecortex API key is required. The key is missing, mistyped, revoked or expired. Print the length of ONECORTEX_API_KEY in the process that calls: an empty variable is the most common cause.
404, That agent does not exist. Copy the agent’s ID from its page. If the ID is right, the key is scoped to another agent, or belongs to another organization.
The reply is empty, or stops part way
Your client is probably ignoringevent: error. A stream that has started has already sent 200 OK, so a failure after that arrives as an error event, and a client that reads only text and done shows it as an empty success. Handle error as the snippets on the invoke API do.
If there is no error event and no done, the connection closed. Check your client’s read timeout: an agent can be silent for a long time while it works, and Onecortex sends a : ping comment every 15 seconds to keep the connection open. A timeout shorter than that closes it.
A call answers 502 agent_error
Your agent’s code raised. The response’s message is the exception’s type and message, and the full traceback is in the agent’s Logs tab, next to the call. Reproduce it locally with the same prompt.The agent forgets the conversation
A session keeps your agent’s running instance, not a stored history. Send the samesessionId on every call of a conversation, and keep memory that must last in your agent: a LangGraph checkpointer, or your own store. An instance stops after 15 minutes idle, after an hour at most, and whenever a new version goes live. See Sessions.
The logs show nothing for a call
If input and output logging is turned off in the agent’s Settings, the prompt and the reply are not logged. Your own output, fromprint, logging or console, is logged either way. See Logs.
Still stuck
Email [email protected] with the agent ID, the build ID or therequestId, and what you expected. See Support.