Troubleshooting

Find the right place to look when a model is not ready, a run is blocked, or a workflow does not behave as expected.

Start with the selected environment, the published version, and the identity trying to run it. Then locate the stage that failed: setup, publication, admission, execution, or result checks.

Setup and publication

Symptom	What to check
No model to select	Register a model in Connections in this environment. Confirm provider, exact model identifier, and declared capabilities.
Model is not ready	Inspect profile and connection status, required review, credential binding, and execution policy. See Models and connections.
Publish is blocked	Save the draft, fix validation issues, and resolve missing model or collection bindings. Check your editing role.
Test reports valid input but produces no answer	Draft Test checks the input schema. Publish a version and choose Run to execute the model.
A setting is missing	Check the selected scope, permissions, and sample-data status. Some advanced definition options are available through the SDK/API rather than an editor tab.
Workflow edits will not save	Check the save error. If another editor changed the draft, load the newest version and reconcile your work before publishing.

Starting and waiting

Symptom	What to check
Published agent cannot run	Use Access for the actual user or API key. Dependencies need access as well as the target.
Client app cannot start an agent	Check the named target, registered app, current client session, user grants, and origin settings. See Access and client apps.
Schedule uses old behavior	Inspect its version. Publication does not move schedules or event-trigger bindings automatically.
Event is refused or too old	Inspect payload-schema validation, event timestamp, freshness settings, and hop limit in the trigger's records.
Event does not resume a workflow	Confirm the answer-wait binding, workflow version, Wait node, and matching correlation key.
Run remains queued	Inspect the queue key, busy behavior, paused state, and active run holding a place.
Run awaits input or approval	Respond to the pending request in that run or Inbox. Starting another run will not answer it.

Results and execution

Symptom	What to check
Agent cannot use an attached capability	Check model tool support, binding, loading/discovery settings, resource grants, and any capability-specific setup. Attachment alone does not grant permission.
Knowledge search returns nothing useful	Confirm ingestion/indexing completed, the right collection is bound, and this user and agent can read it. Test the collection's search.
Answer ends abruptly	Inspect the provider attempt's output-token limit and the run's turn, step, tool-call, and timeout limits.
Text appears but the run fails	Streaming text is provisional. Inspect output-schema and required acceptance checks, plus the final failure record.
Workflow mapping cannot find a value	Inspect Data and the executed branch. The producing step must have run on that path, and the reference must select the right field.
Workflow never reaches the new step	Check the Start connection and incoming/outgoing paths. A disconnected node is not executed.
Run needs recovery	Inspect the uncertain action and confirm its external outcome before retrying or starting another run.

Gather the useful evidence

Record the environment, target and version, run identifier, current state, and the last relevant attempt's failure and identifiers. Include the shape of the input and the path taken through a workflow. Avoid sharing secret values from credentials or sensitive customer content.

For API integrations, use Errors and retries and Recovery, diagnostics and usage. For a conceptual mismatch, return to How Core fits together and distinguish the definition, published version, entry point, and run.