Skip to main content

Troubleshooting functions

Each section below is a real symptom — the exact error message where there is one — followed by the cause and the fix. Search this page for the text of the error you are seeing.

Deploy errors​

unsupported 'framework': one of "adk", "langgraph", "crewai", "function"​

Symptom: a POST /v1/agents request fails with status 400 and this message. platformctl functions deploy shows it too, for any function that is not Python.

Cause: functions deploy through the agents endpoint, and the framework form field must be exactly function. Any other value (a typo like functions, or an unknown framework name) is rejected.

Fix: set framework=function in the multipart form, and select a non-Python language with the separate runtime field (nodejs, go, ruby). Note that platformctl functions deploy currently folds the runtime into the framework field itself (for example framework=function-nodejs), which fails this check and triggers exactly this error for anything but Python — deploy non-Python functions through the raw API until the CLI is fixed. See runtimes for the full command.

'runtime' only applies to framework=function​

Symptom: a raw POST /v1/agents request fails with status 400 and this message.

Cause: you sent a runtime field together with an agent framework (adk, langgraph, or crewai). The runtime field selects a function language; agents do not have one, so the combination is rejected rather than silently ignored.

Fix: if you meant to deploy a function, change framework to function. If you meant to deploy an agent, drop the runtime field.

unsupported 'runtime': one of "python", "nodejs", "go", "ruby"​

Symptom: a raw POST /v1/agents request that carries framework=function fails with status 400 and this message.

Cause: the runtime value is not one of the four supported ones. Only an API caller can reach this check: the CLI never sends a runtime field, so a value it does not recognize (--runtime node, --runtime golang) goes into the framework field instead and comes back as the unsupported 'framework' error above.

Fix: use python, nodejs, go, or ruby.

missing or invalid 'name' (must be a lowercase DNS label)​

Symptom: the deploy fails with status 400 and this message.

Cause: function names (like agent names) must be lowercase DNS labels: lowercase letters, digits, and dashes; starting with a letter; ending with a letter or digit; at most 63 characters. My_Function and 2nd-try both fail.

Fix: rename — for example my-function or second-try. Also note that agents and functions share one flat name namespace per project, so a name already used by an agent is not available for a function. Commands that address an existing function by name — status, invoke, logs, delete — reject a bad name with a different message, invalid agent name (must be a lowercase DNS label), for the same reason.

failed to build/deploy (see platformctl logs ...)​

Symptom: platformctl functions deploy ends with:

hello-fn failed to build/deploy (see `platformctl logs hello-fn`)

Cause: the platform accepted your upload but the build or rollout failed — most often a dependency install error (requirements.txt, package.json, Gemfile) or, for Go, a compile error. One Go-specific build failure worth knowing:

go function requires a handler.go with a Handle(event) func

which means you deployed with --runtime go but the directory has no handler.go.

Fix: run platformctl logs hello-fn to read the failure, correct the code or dependency file, and deploy again. Each deploy replaces the whole source tree, so there is no partial state to clean up.

timed out after 5m0s waiting for hello-fn (last status: building)​

Symptom: the CLI gives up after five minutes of polling.

Cause: the build is slow (large dependency installs are the usual reason) or the cluster is busy. The build itself has not necessarily failed — the CLI just stopped waiting.

Fix: check again with platformctl status hello-fn. If it eventually reaches ready, nothing is wrong. If it sits in building indefinitely or flips to failed, read platformctl logs hello-fn and trim your dependencies.

The upload is rejected as too large, or the console refuses my files​

Symptom: a CLI deploy fails on upload, or the web console refuses the directory.

Cause: the CLI uploads your entire directory — there is no ignore mechanism — with a 100 MiB cap. A stray .venv/, node_modules/, or .git/ directory is the usual culprit. The console is stricter than the CLI: it caps archives at 32 MiB, uploads text files only, and limits files to 1 MiB each — its error messages tell you to use platformctl when you hit them.

Fix: deploy from a clean directory containing only your handler and dependency file, and use platformctl functions deploy for anything the console cannot upload.

Wrong behavior after deploy​

My Python function is detected as another language​

Symptom: you wrote a Python function, but the CLI prints framework=function-nodejs (or -go, -ruby) and the deploy fails with unsupported 'framework': one of "adk", "langgraph", "crewai", "function".

Cause: the CLI auto-detects the runtime from file names — handler.js means nodejs, handler.go means go, handler.rb means ruby, anything else means python — and folds that choice into the framework field. A leftover handler file from another language wins the detection, and the token it produces is one the control plane does not accept.

Fix: remove the stray handler file, or force the language with --runtime python. The choice is remembered: redeploys keep the same runtime automatically.

The console has no Redeploy button on my function​

Symptom: the redeploy shortcut you see on an agent's page is missing on a function's page.

Cause: the console's Functions page deliberately leaves it out and offers "Update source" instead. The endpoint behind it, POST /v1/agents/{name}/redeploy, is not restricted — it rebuilds from the stored source using the framework recorded on the deployment, so a function is rebuilt as a function, in its original runtime.

Fix: to ship a new version of a function, run platformctl functions deploy ./my-dir --name my-function again, or use the console's "Update source" action on the function's page. Either path rebuilds the function in its original runtime.

Runtime errors​

{"error": "handler raised: ..."}​

Symptom: callers get a 500 (plain HTTP) or the event broker logs a 400 (CloudEvents) with this body.

Cause: your handler threw an exception. The platform catches it and returns a real HTTP response instead of dropping the connection; for CloudEvents it uses 400 on purpose, so the broker stops redelivering an event that will always fail. See HTTP and events.

Fix: the text after handler raised: is the exception message. The full stack trace is in the function's logs: platformctl logs my-function --history.

{"error": "body exceeds 8388608 bytes"}​

Symptom: a POST to the function returns status 413 with this body. On the Go runtime the body reads {"error": "body too large or unreadable"} instead.

Cause: the request body is over the 8 MiB event cap. The handler never ran.

Fix: send less data per request — for large payloads, pass a reference (an object-storage location, an ID) instead of the payload itself.

Logs and authentication​

platformctl logs shows nothing, or the function has no running pod​

Symptom: platformctl logs my-function returns nothing useful for an idle function, or --history prints no persisted logs.

Cause: an idle function is scaled to zero — there is no live process to tail. Plain logs tails the live copy; --history reads persisted lines that survive scale-to-zero. no persisted logs means the function has not logged anything yet.

Fix: use platformctl logs my-function --history after the function has served at least one request. Do not combine the flags:

--follow and --history are mutually exclusive: --history reads persisted logs, --follow tails the live pod

this is a management endpoint and requires authentication​

Symptom: deploy, status, logs, or delete fails with a 401 carrying this message (the full text tells you how to sign in), while platformctl invoke keeps working.

Cause: invoking a function (the data plane) is open by default in this alpha, but everything that manages one requires a credential — and yours is missing or expired. Sign-in sessions last 12 hours. The CLI's error also names which credential source it tried.

Fix: run platformctl login again, or set $CAI_TOKEN to an API key. See API authentication and service accounts and API keys.

not found on a project that definitely exists​

Symptom: requests against a project return 404 not found even though the project exists.

Cause: by design, the platform answers 404 — never 403 — when you hold no grant on a project, so outsiders cannot probe which projects exist. A 404 here usually means "you are not a member", not "wrong URL".

Fix: confirm which projects you can see with platformctl projects list, and ask a project admin to add you.

Still stuck?​