Troubleshooting: Deploy failures

The deploy endpoint returns a structured detail.error for every failure. Match yours below.

412 missing_scaigrid_credentials#

{ "detail": { "error": "missing_scaigrid_credentials",
              "message": "no ScaiGrid credentials for tenant 'acme'",
              "fix": "Sign in with ScaiKey, or set this tenant's API key via POST /v1/tenants/me/scaigrid_credentials." } }

The backend couldn't find any usable ScaiGrid credentials.

Fix: A tenant admin sets the tenant's API key via:

1
2
3
4

curl -X POST "https://scaiflow.example/api/v1/tenants/me/scaigrid_credentials" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "sgk_xxxxxxxxxx", "base_url": "https://scaigrid.scailabs.ai" }'

Or, for dev: set SCAIGRID_API_KEY env var on the backend process (only honored when no tenant key is set).

502 scaiqueue_auth#

{ "detail": { "error": "scaiqueue_auth",
              "message": "permission_denied: need scaiqueue:manage",
              "fix": "Caller needs scaiqueue:manage to provision missing scopes/queues." } }

The pre-deploy ScaiQueue provisioning step (which runs when flow.config.scaiqueue is set) couldn't authenticate to ScaiQueue.

Fix: Grant scaiqueue:view + scaiqueue:manage to the caller's principal (via ScaiKey). For tenant-tier credentials, ensure the tenant's API key has those scopes too.

If you don't need pre-deploy provisioning (e.g. the scope already exists), just remove flow.config.scaiqueue and ScaiFlow will skip the step. You'll still need to reference scopes/queues by slug in node configs, but the deploy won't fail.

502 scaiqueue_provision_failed#

{ "detail": { "error": "scaiqueue_provision_failed",
              "message": "...",
              "scope": "support", "queue": "review" } }

Provisioning failed for non-auth reasons (slug conflict, network error, etc.). The message is the upstream error.

Fix: Check whether the scope already exists with a different config than what your flow declares. ScaiQueue's POST on slug conflict raises 409 (no return-existing semantics); ensure_* helpers re-list on 409, but if the second list also fails or shows a config mismatch, deploy aborts.

502 scaicore_create_failed#

{ "detail": { "error": "scaicore_create_failed",
              "message": "verifier error: ...",
              "status": 400 } }

ScaiGrid rejected the manifest. Usually a verifier error.

Fix: Compile locally with verification on and read the diagnostic:

1

scaiflow compile my-flow.flow.json --format ir

The verifier catches IR shape mismatches that the YAML loader silently tolerates. Common causes:

• Plugin call missing a required arg.
• llm_role referenced but not declared (the canvas + compiler catch this before deploy now, but older flows might slip through).
• Block kind not in ScaiCore's closed set (shouldn't happen — file a bug if it does).

502 scaicore_publish_failed#

{ "detail": { "error": "scaicore_publish_failed", "core_id": "core_xxx" } }

The Core was created successfully but the /publish step failed.

The Core is still deployed and invokable. It just isn't registered as a chat model. To retry the publish manually:

1
2
3

curl -X POST "https://scaigrid.scailabs.ai/v1/modules/scaicore/cores/${CORE_ID}/publish" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{}'

Or re-deploy via the canvas (idempotent — updates the existing Core, re-tries the publish).

Changing the publish state on an already-deployed Core#

Setting publish_as_model: false and re-deploying does NOT un-publish — that requires:

1
2

curl -X DELETE "https://scaigrid.scailabs.ai/v1/modules/scaicore/cores/${CORE_ID}/publish" \
  -H "Authorization: Bearer ${TOKEN}"

A future ScaiFlow release will detect the transition and call this automatically.

Deploy succeeds but no events show up#

The Live Runs panel polls GET /v1/scaicore/events. Check:

• ScaiGrid is actually emitting events (call GET /v1/modules/scaicore/events?core_id=$CORE_ID directly).
• Your tenant has scaicore:view on the calling principal.
• The flow's core_id is registered in /v1/flows/{id}/deployments (the canvas reads this to know which Cores to poll for events for this flow).
• auth_mode is scaikey — events polling is gated on it.