Troubleshooting

Warning

Project Neo is currently in Technical Preview. Features described in this section may change before general availability.

This page lists the common failures when authoring a configuration, deploying it, calling the API directly, and running scheduled tasks, each as a symptom, its cause, and the fix. For the full command surface, see the CLI Reference page, and for the HTTP status codes, see the API Reference page.

Reading a Publish-Rejected Result

Both genai lint and genai deploy report validation failures the same way: a list, where each entry pairs the location of the problem with a message. On the command line the output looks like this:

publish rejected:
  - agents.deep_research.prefers.inference.model: unknown Model 'sonnet-typo'
  - Model.claude-haiku.auth.secret: handle 'anthropic_token' not found in secret store

Over the HTTP API, a deploy returns the same information as a 422 response whose detail.failures field is the list of failures. Read each entry as “at this path, this is what is wrong”. The path names the resource and the field, so you can go straight to the file and line that need attention. A deploy fails as a whole: fix every listed entry and deploy again. When a deploy is rejected, the previously deployed configuration snapshot stays in place unchanged.

Run genai lint before deploying. It runs every check that does not need the cluster, so it catches most of these failures offline, with no network and no credentials.

Deploy Is Rejected

A resource reference does not exist

Symptom. publish rejected with a message such as unknown Model 'sonnet-typo', unknown parent agent 'research_template', or unknown TraitDimension 'style'.

Cause. A preference, constraint, pin, or extends names a resource that the project does not publish. Identity is the combination of kind and id, so the referenced id must match an authored resource of that kind exactly.

Fix. Correct the value to an id that exists, or add the missing resource. For example, inference.model must name a Model whose metadata.id matches. See the Resource Reference page.

No model is set for the project

Symptom. publish rejected with 'inference.model' has no built-in default and must be set in Project.prefers or Project.pins.

Cause. inference.model is the one setting with no built-in default, and every project must set it.

Fix. Set inference.model in the Project resource, under prefers for an overridable default or pins for a fixed value. See the Preference Reference page.

A deploy is rejected for an unresolvable credential handle

Symptom. A deploy is rejected with handle 'anthropic_token' not found in secret store, or with handle 'anthropic_token' resolves to OAuthToken, expected BearerToken.

Cause. A resource auth block references a secret handle that is not bound on the cluster, or is bound to the wrong kind of credential for its auth type. The names in the second message are the internal names of the credential kinds rather than the auth type you wrote in the file.

Fix. Register the credential for the handle, matching the auth type on the resource, then deploy again. See the Registering a Handle section.

A Deployed Configuration Misbehaves

These deploy without error, but the agents do not behave as the files suggest.

An agent does not appear in the picker

Symptom. A user cannot select an agent in the Chat dashboard, even though it deployed successfully.

Cause. Only entrypoint agents appear in the picker. An agent without entrypoint: true is not selectable, whether it is a subagent target or authored for internal use.

Fix. Set entrypoint: true on the agent. To also control its position in the picker, set entrypoint_order. See the Authoring Agents page.

A knowledge graph or MCP server returns nothing

Symptom. An agent never uses a knowledge graph or an MCP server that is deployed in the project.

Cause. The capability is off for that conversation, or the project publishes no resource of the backing kind. A capability exposes every resource of its kind that the project publishes, so with none published, there is nothing to reach.

Fix. Confirm the switch resolves on: source.knowledge_graph.enabled for knowledge graphs, capability.mcp.enabled for MCP servers. Confirm the project publishes at least one resource of that kind. See the Preference Reference page.

A preference never takes effect

Symptom. A value set in a preference is not the value that resolves at runtime.

Cause. A constraint or a pin, from the project or the selected agent, does not admit the value, so resolution falls through to the next source. Runtime is lenient: an inadmissible value does not fail the request, it is skipped.

Fix. Read the constrains and pins blocks of the Project resource and of the selected agent, and check whether either of them admits the value you set. Then either set a value they allow, or relax the constraint. See the Authoring Agents page.

genai explain answers the same question against your files, showing which source supplies the winning value and whether each contribution was selected, shadowed, or invalid. It resolves locally rather than querying the deployed configuration, so use it to reason about what you have authored, and read it as a statement about your files rather than as a report from the running project. For what the command covers, see the CLI Reference page.

Calling the API

A request returns 401

Symptom. Any route returns 401, either on the first call or after a client has been running for a while.

Cause. No credentials reached the service, or the access token is invalid or has expired. A common first-time cause is sending the refresh token itself: the Authorization header takes an access token, and a refresh token in its place is refused. Access tokens are also short-lived, so a client that exchanges once and then runs for a long time starts failing when its token expires.

Fix. Exchange the refresh token for an access token, send that in the Authorization header, and exchange again whenever a call answers 401. See the Authenticating a Request section on the API Reference page.

A request returns 403

Symptom. Any configuration route, such as a deploy, status, log, snapshot, resources, or reseed request, returns 403. A task route can return it too.

Cause. The caller is authenticated but not allowed to make this call. Two separate checks return this status. Read access to the project is checked before the request reaches the service, and the Administrator role is checked by the service. So the caller either cannot read the target project at all, or can read it but does not hold the Administrator role on it.

Fix. Confirm that the user the token belongs to can open the target project, then confirm that the user holds the project-level Administrator role, or the server-level Administrator role which carries it on every project. See the Authentication and Authorization section on the API Reference page, and for how roles are assigned, the Squirro Roles & Permissions page.

A request returns 404 on a project that exists

Symptom. A status, snapshot, or resources request returns 404 even though the project ID is correct.

Cause. These routes report the deployed configuration, and the project has none yet. A project you have never deployed to has no configuration to read.

Fix. Deploy a configuration to the project first. On a task route, a 404 means something else: the task or run does not exist, or it belongs to another user, since each user sees only their own tasks.

A reseed returns 409

Symptom. genai reseed returns 409 and refuses to run.

Cause. The project has an operator-deployed configuration snapshot, which the platform does not replace with the bundled workspace unless you explicitly ask it to.

Fix. If replacing the operator-deployed configuration is intended, pass --force. This discards the current configuration, which is recoverable only from version control. See the genai reseed section.

A reseed returns 500

Symptom. genai reseed returns 500, with an error body naming a workspace and a list of failures.

Cause. The bundled workspace that ships with the platform could not be built into a valid configuration, so there was nothing to deploy. This is a fault in what the platform shipped, not in anything you authored.

Fix. Nothing in your own project files will fix this. Report the failures to Squirro support, and in the meantime deploy your own configuration with genai deploy instead of reseeding.

Scheduled Task Failures

A task never fires

Symptom. A task exists and its schedule has passed, but no run appears in its history.

Cause. A task has two switches, and it fires on its schedule only when both are on: the task-level enabled, and the switch on the schedule itself. Either one being off keeps it idle. A task also fires in the timezone recorded on it, so a schedule that looks overdue in your own timezone may not be due yet in the one the task uses.

Fix. Read the task with genai task get and check both switches and the timezone. The second switch appears as auto-fire in the command line output, is set with --auto-fire and --no-auto-fire, and is named trigger.enabled over the API. Turn the task on, or turn auto-firing back on, as needed. To confirm the task itself works, fire it once with genai task run, which runs whatever the two switches are set to. See the genai task section on the CLI Reference page.

A task run refuses a tool call

Symptom. A scheduled run finishes, but its conversation shows that a tool call was refused, and the agent worked around the refusal.

Cause. A scheduled run has nobody present to approve anything, so approval fails closed: a tool that needs approval and matches no rule is refused rather than allowed. A rule on the task cannot change that on its own, because a task can only tighten the project approval policy. Both approve and interactive set by the task become defer on a scheduled run, which parks the run for a person to approve later rather than letting it proceed.

Fix. To let a scheduled run make the call with no one approving it, grant approve for that tool in the hitl block of the Project resource, which is the only place that can grant it. To have the run wait for a person instead, add a rule to the task and approve the call afterwards. See the Scheduled Tasks and Approvals page.

Creating a task returns 409

Symptom. genai task create fails with 409 and a message such as Task limit reached (100 per user in this project). Delete a task first., while existing tasks continue to work.

Cause. The number of tasks one user may hold in a project is capped, and the limit has been reached. The message states the limit in force on your instance. The cap is per user and per project, so it counts your own tasks in that project alone.

Fix. Delete a task you no longer need, then create the new one. The limit is a service setting, so an operator can raise it if the work genuinely needs more tasks.

Retrying a run returns 409

Symptom. genai task retry fails with 409 on a run that has finished.

Cause. Only a run that failed, or that stopped early while keeping the output it had produced, can be retried. A run that succeeded, or one that is still going, cannot.

Fix. Check the status of the run with genai task runs. To run the task again from the start, use genai task run instead, which fires a new run regardless of what earlier runs did.

Listing tasks returns 400

Symptom. A task list request returns 400 with a message such as Invalid sort field 'created'; allowed: created_at, last_execution_at, name, next_execution_at, updated_at.

Cause. The list accepts a fixed set of sort fields, and anything else is refused rather than ignored.

Fix. Sort by one of the fields the message lists. See the Scheduled Tasks section on the API Reference page.